Data Dictionary

The data dictionary module provides schema introspection, table and column metadata, foreign key resolution, dependency ordering, and database version capability profiling.

Metadata Types

class sqlspec.data_dictionary.TableMetadata

Bases: TypedDict

Metadata for a database table.

class sqlspec.data_dictionary.TableDetails

Bases: ObjectMetadata

Rich table metadata including optional DDL status.

__init__(identity, *, table_type=None, source=None, ddl=None, attributes=None)

to_dict()

Serialize table details.

Return type:

dict[str, object]

class sqlspec.data_dictionary.ColumnMetadata

Bases: TypedDict

Metadata for a database column.

schema_name

Schema containing the table.

table_name

Table name.

column_name

Name of the column.

data_type

Dialect or canonical data type name.

is_nullable

Whether the column allows null values.

column_default

Default value expression or sequence default.

ordinal_position

1-based column position in the table.

max_length

Maximum character or byte length.

numeric_precision

Numeric precision.

numeric_scale

Numeric scale.

is_primary

Whether the column is part of the primary key.

is_unique

Whether the column has a unique constraint.

extra

Dialect-specific extra column attributes.

column_type

Full column type specification (e.g. on MySQL).

column_key

Index key designation (e.g. MySQL PRI, UNI, MUL).

identity_generation

Identity column generation type (a for ALWAYS, d for BY DEFAULT).

sequence_name

Name of the sequence owned by a serial or identity column.

is_generated

Whether the column is a generated/computed column.

class sqlspec.data_dictionary.ColumnDetails

Bases: ObjectMetadata

Rich metadata for a column.

class sqlspec.data_dictionary.ForeignKeyMetadata

Bases: object

Metadata for a foreign key constraint.

__init__(table_name, column_name, referenced_table, referenced_column, constraint_name=None, schema=None, referenced_schema=None)

class sqlspec.data_dictionary.IndexMetadata

Bases: TypedDict

Metadata for a database index.

class sqlspec.data_dictionary.IndexDetails

Bases: ObjectMetadata

Rich metadata for an index.

class sqlspec.data_dictionary.PartitionMetadata

Bases: ObjectMetadata

Rich metadata for partition, clustering, storage, or table options.

class sqlspec.data_dictionary.PrivilegeMetadata

Bases: ObjectMetadata

Rich metadata for a grant, role edge, or privilege.

class sqlspec.data_dictionary.RoutineMetadata

Bases: ObjectMetadata

Rich metadata for a routine, function, procedure, or package member.

class sqlspec.data_dictionary.TriggerMetadata

Bases: ObjectMetadata

Rich metadata for a trigger or database event.

class sqlspec.data_dictionary.ViewMetadata

Bases: ObjectMetadata

Rich metadata for a view or materialized view.

Database Capability and Versions

class sqlspec.data_dictionary.VersionInfo

Bases: object

Parsed database version info.

__init__(major, minor=0, patch=0)

Initialize version info.

Parameters:

• major (int) -- Major version number

• minor (int) -- Minor version number

• patch (int) -- Patch version number

property version_tuple: tuple[int, int, int]

Get version as tuple for comparison.

__str__()

String representation of version info.

Return type:

str

__repr__()

Detailed string representation.

Return type:

str

__eq__(other)

Check version equality.

Return type:

bool

__lt__(other)

Check if this version is less than another.

Return type:

bool

__le__(other)

Check if this version is less than or equal to another.

Return type:

bool

__gt__(other)

Check if this version is greater than another.

Return type:

bool

__ge__(other)

Check if this version is greater than or equal to another.

Return type:

bool

__hash__()

Make VersionInfo hashable based on version tuple.

Return type:

int

class sqlspec.data_dictionary.FeatureFlags

Bases: TypedDict

Typed feature flags for data dictionary dialects.

class sqlspec.data_dictionary.FeatureVersions

Bases: TypedDict

Typed feature version requirements for data dictionary dialects.

class sqlspec.data_dictionary.MetadataCapabilityProfile

Bases: object

Capability report for one adapter and dialect.

__init__(dialect, *, adapter=None, capabilities=())

get(domain)

Return capability for a domain, or unknown when it has not been reported.

Return type:

MetadataCapability

to_dict()

Serialize the profile with stable string enum values.

Return type:

dict[str, str | tuple[dict[str, str | tuple[str, ...]], ...] | None]

classmethod from_domains(dialect, adapter, domains)

Create an unsupported profile for domains without implementation.

Return type:

MetadataCapabilityProfile

Data Dictionary Loader and Queries

class sqlspec.data_dictionary.DataDictionaryLoader

Bases: object

Loads and manages data dictionary SQL for all dialects.

__init__()

Initialize the data dictionary loader.

get_domain_query(dialect, domain, query_name, *, mode=None, version=None, required_features=())

Get a data-dictionary query by dialect, domain, and query name.

Parameters:

• dialect (str) -- Dialect or dialect alias.

• domain (str) -- Metadata domain name.

• query_name (str) -- Query name inside the domain pack.

• mode (str | None) -- Optional SQL dialect mode for multi-mode engines.

• version (VersionInfo | None) -- Optional database version used for feature gates.

• required_features (tuple[str, ...]) -- Feature flags/version gates required by the query.

Return type:

MetadataQuery

Returns:

MetadataQuery containing SQL when supported, otherwise an unsupported status.

get_domain_queries(dialect, domain, query_names, *, mode=None, version=None, required_features=())

Get multiple data-dictionary queries from one domain pack.

Parameters:

• dialect (str) -- Dialect or dialect alias.

• domain (str) -- Metadata domain name.

• query_names (Iterable[str]) -- Query names inside the domain pack.

• mode (str | None) -- Optional SQL dialect mode for multi-mode engines.

• version (VersionInfo | None) -- Optional database version used for feature gates.

• required_features (tuple[str, ...]) -- Feature flags/version gates required by every query.

Return type:

dict[str, MetadataQuery]

Returns:

Ordered mapping of normalized query names to metadata query results.

get_domain_query_text(dialect, domain, query_name, *, mode=None, version=None, required_features=())

Get raw SQL text for a domain query, or None when unsupported.

Return type:

str | None

get_dialect_config(dialect)

Get static configuration for a dialect.

Parameters:

dialect (str) -- Dialect name.

Return type:

DialectConfig

Returns:

DialectConfig for the dialect.

list_dialects()

List available SQL dialects.

Return type:

list[str]

Returns:

List of dialect names with SQL directories.

class sqlspec.data_dictionary.MetadataQuery

Bases: object

Loaded data-dictionary query plus capability status.

__init__(dialect, domain, name, *, sql=None, mode=None, capability=None, warnings=())

property is_supported: bool

Return whether the query is available and executable.

property query_text: str | None

Return raw SQL text when the query is supported.

classmethod unsupported(dialect, domain, name, *, mode=None, source=MetadataSource.UNKNOWN, risks=(), warnings=())

Create a structured unsupported query result.

Return type:

MetadataQuery

to_dict()

Serialize the query status.

Return type:

dict[str, object]

class sqlspec.data_dictionary.MetadataResult

Bases: object

Uniform result envelope for metadata domain lookups.

__init__(domain, *, capability=None, items=(), warnings=())

classmethod unsupported(domain, *, source=MetadataSource.UNKNOWN)

Create a standard unsupported-domain result.

Return type:

MetadataResult

to_dict()

Serialize the result envelope.

Return type:

dict[str, object]

Helper Functions

sqlspec.data_dictionary.get_data_dictionary_loader()

Get singleton data dictionary loader instance.

Return type:

DataDictionaryLoader

Returns:

DataDictionaryLoader singleton.

sqlspec.data_dictionary.get_dialect_config(dialect)

Get configuration for a dialect.

Parameters:

dialect (str) -- Dialect name.

Return type:

DialectConfig

Returns:

DialectConfig for the requested dialect.

Raises:

ValueError -- When the dialect is unknown.

sqlspec.data_dictionary.register_dialect(config)

Register a dialect configuration.

Parameters:

config (DialectConfig) -- Dialect configuration to register.

Return type:

None

sqlspec.data_dictionary.list_registered_dialects()

Return registered dialect names.

Return type:

list[str]

Returns:

List of registered dialect names.

sqlspec.data_dictionary.sort_dependencies(objects, edges, *, order='create')

Sort metadata objects by typed dependency edges.

Parameters:

• objects (Iterable[ObjectIdentity]) -- Initial object identities to include in the graph.

• edges (Iterable[DependencyEdge]) -- Dependency edges. Edge endpoints are added to the graph automatically.

• order (Literal['create', 'drop']) -- "create" for dependencies before dependents, "drop" for dependents before dependencies.

Return type:

DependencySortResult

Returns:

Ordered objects plus cycle diagnostics if cycles prevented a complete order.