Data Dictionary¶

from sqlspec.data_dictionary import (
    ColumnMetadata,
    ColumnProfileMetadata,
    ConstraintMetadata,
    DataDictionaryLoader,
    DDLResult,
    DependencyEdge,
    DependencySortResult,
    DialectConfig,
    ForeignKeyMetadata,
    IndexMetadata,
    MetadataCapabilityProfile,
    MetadataResult,
    RoutineMetadata,
    SystemMetadataRequest,
    SystemMetadataResult,
    TableMetadata,
    TriggerMetadata,
    VersionInfo,
    ViewMetadata,
    dependency_edges_from_foreign_keys,
    dependency_edges_from_metadata,
    get_data_dictionary_loader,
    get_dialect_config,
    list_registered_dialects,
    normalize_dialect_name,
    register_dialect,
    sort_ddl_results,
    sort_dependencies,
)

Cross-database catalog introspection metadata, DDL extraction, column profiling, capability profiles, dialect registry, and foreign-key topological sorting. Access runtime introspection through driver.data_dictionary on any SyncDriverAdapterBase or AsyncDriverAdapterBase session (see Runtime Introspection & DDL Synthesis and the Dialect SQL Catalogs).

Loader & Dialect Registry¶

DataDictionaryLoader ¶

Loads and manages data dictionary SQL for all dialects.

get_data_dictionary_loader ¶

get_data_dictionary_loader()

Get singleton data dictionary loader instance.

Returns:

Type	Description
`DataDictionaryLoader`	DataDictionaryLoader singleton.

get_dialect_config ¶

get_dialect_config(dialect)

Get configuration for a dialect.

Parameters:

Name	Type	Description	Default
`dialect`	`str`	Dialect name.	required

Returns:

Type	Description
`DialectConfig`	DialectConfig for the requested dialect.

Raises:

Type	Description
`ValueError`	When the dialect is unknown.

list_registered_dialects ¶

list_registered_dialects()

Return registered dialect names.

Returns:

Type	Description
`list[str]`	List of registered dialect names.

normalize_dialect_name ¶

normalize_dialect_name(dialect)

Normalize dialect names to canonical registry keys.

Parameters:

Name	Type	Description	Default
`dialect`	`str`	Input dialect name.	required

Returns:

Type	Description
`str`	Canonical dialect key.

register_dialect ¶

register_dialect(config)

Parameters:

Name	Type	Description	Default
`config`	`DialectConfig`	Dialect configuration to register.	required

Schema & Catalog Metadata Types¶

VersionInfo ¶

Parsed database version info.

TableMetadata ¶

Bases: TypedDict

Introspected catalog metadata for a database table or view.

Attributes:

Name	Type	Description
`schema_name`	`str`	Database schema owning the table.
`table_name`	`str`	Unquoted table or view identifier.
`table_type`	`str`	Catalog object classification (such as `BASE TABLE` or `VIEW`).
`table_catalog`	`str`	Database or catalog name reported by `information_schema`.
`table_schema`	`str`	Raw `information_schema` schema column alias when distinct from `schema_name`.
`dependency_level`	`int`	Zero-based foreign-key topological ordering depth for safe DDL/fixture creation.
`level`	`int`	Dialect query alias for `dependency_level` in recursive hierarchy scans.

ColumnMetadata ¶

Bases: TypedDict

Introspected catalog metadata for a single database column.

Attributes:

Name	Type	Description
`schema_name`	`str`	Database schema or namespace owning the parent table.
`table_name`	`str`	Unquoted name of the parent table or view.
`column_name`	`str`	Unquoted column identifier.
`data_type`	`str`	Dialect or canonical SQL data type name.
`is_nullable`	`str \| bool \| None`	Nullability indicator returned by the catalog (boolean or `YES`/`NO`).
`column_default`	`str \| None`	SQL default value expression or sequence generator expression, if defined.
`ordinal_position`	`int`	One-based ordinal position of the column within the table.
`max_length`	`int`	Maximum character or byte length for string and binary types.
`numeric_precision`	`int`	Total digit precision for exact or approximate numeric types.
`numeric_scale`	`int`	Fractional digit scale for exact numeric types.
`is_primary`	`bool \| int`	Whether the column participates in the table primary key.
`is_unique`	`bool \| int`	Whether the column is covered by a single-column unique constraint.
`extra`	`str`	Dialect-specific extra column modifiers (such as `auto_increment`).
`column_type`	`str`	Full dialect column type specification including length or enum members.
`column_key`	`str`	Catalog key classification code (such as MySQL `PRI`, `UNI`, or `MUL`).
`identity_generation`	`str \| None`	Identity generation mode (`ALWAYS`, `BY DEFAULT`, or `BY DEFAULT ON NULL`), if applicable.
`is_identity`	`bool \| int \| str \| None`	Whether the column is an identity column reported by the catalog.
`sequence_name`	`str \| None`	Backing sequence name owned by a serial or identity column.
`is_generated`	`bool \| int \| str \| None`	Whether the column is a computed or virtual/stored generated column.
`generation_expression`	`str \| None`	SQL expression defining a virtual or stored generated column.
`is_hidden`	`bool \| int \| str \| None`	Whether the column is hidden or system-dropped.
`column_comment`	`str \| None`	Comment or description attached to the column.

ColumnProfileMetadata ¶

Profile statistics and inferred SQL type for a database table column.

IndexMetadata ¶

Bases: TypedDict

Introspected catalog metadata for a table index.

Attributes:

Name	Type	Description
`schema_name`	`str`	Database schema owning the indexed table.
`table_name`	`str`	Unquoted name of the indexed table.
`index_name`	`str`	Unquoted index identifier.
`columns`	`list[str] \| str \| None`	Ordered column names included in the index key (as list or comma-delimited string).
`is_unique`	`bool \| int`	Whether the index enforces uniqueness.
`is_primary`	`bool \| int`	Whether the index backs the primary key constraint.
`expression`	`str \| None`	Single expression for expression-based indexes.
`expressions`	`str \| None`	Comma-separated expressions for expression-based indexes.

ForeignKeyMetadata ¶

Metadata for one column of a foreign key constraint.

on_delete and on_update hold the referential action (CASCADE, SET NULL, SET DEFAULT, RESTRICT, NO ACTION) when the catalog exposes it, otherwise None.

ConstraintMetadata ¶

Bases: ObjectMetadata

Rich metadata for a constraint.

ViewMetadata ¶

Bases: ObjectMetadata

Rich metadata for a view or materialized view.

RoutineMetadata ¶

Bases: ObjectMetadata

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

TriggerMetadata ¶

Bases: ObjectMetadata

Rich metadata for a trigger or database event.

DDLResult ¶

DDL text and fidelity status for one database object.

Capability Profiles & Result Envelopes¶

DialectConfig ¶

Static configuration for a database dialect.

MetadataCapabilityProfile ¶

Capability report for one adapter and dialect.

MetadataResult ¶

Uniform result envelope for metadata domain lookups.

SystemMetadataRequest ¶

Opt-in request for system and performance metadata.

Parameters:

Name	Type	Description	Default
`domain`	`str`	System metadata domain to query.	required
`include_system`	`bool`	Enable system metadata domains such as settings or sessions.	`False`
`include_performance`	`bool`	Enable performance metadata domains such as statistics or history.	`False`
`allow_billed_metadata`	`bool`	Permit domains that may incur cloud or service billing.	`False`
`allow_license_gated_diagnostics`	`bool`	Permit license-gated diagnostics such as AWR/ASH.	`False`
`include_sensitive`	`bool`	Disable default row redaction for this request.	`False`
`table`	`str \| None`	Optional table target for table-scoped metadata.	`None`
`schema`	`str \| None`	Optional schema target for table-scoped metadata.	`None`
`redaction_policy`	`SystemMetadataRedactionPolicy \| None`	Optional explicit row redaction policy.	`None`

SystemMetadataResult ¶

Result envelope for system and performance metadata.

Parameters:

Name	Type	Description	Default
`request`	`SystemMetadataRequest`	Request that produced the result.	required
`capability`	`SystemMetadataCapability`	Capability status for the request domain.	required
`rows`	`tuple[Mapping[str, object], ...]`	Redacted metadata rows.	`()`
`source`	`MetadataSource \| str \| None`	Metadata source override.	`None`
`warnings`	`tuple[str, ...]`	Additional result warnings.	`()`
`redactions`	`tuple[str, ...]`	Redacted fields.	`()`

Dependency Graph & Topological Sorting¶

DependencyEdge ¶

Typed dependency edge between two metadata objects.

from_object is the dependent object and to_object is the prerequisite object. Creation order normally places to_object before from_object; drop order reverses it.

DependencySortResult ¶

Result from dependency graph sorting.

dependency_edges_from_foreign_keys ¶

dependency_edges_from_foreign_keys(
    foreign_keys, *, dialect=None, source=MetadataSource.CATALOG
)

Convert FK metadata into typed dependency edges.

dependency_edges_from_metadata ¶

dependency_edges_from_metadata(dependencies, *, dialect=None, source=None)

Convert rich dependency metadata rows into typed dependency edges.

Dependency query packs do not all return the same vendor column names. This helper accepts SQLSpec's rich DependencyMetadata wrapper and looks for stable attribute aliases such as referenced_name, referenced_schema, referenced_type, kind, strength, and confidence.

sort_dependencies ¶

sort_dependencies(objects, edges, *, order='create')

Sort metadata objects by typed dependency edges.

Parameters:

Name	Type	Description	Default
`objects`	`Iterable[ObjectIdentity]`	Initial object identities to include in the graph.	required
`edges`	`Iterable[DependencyEdge]`	Dependency edges. Edge endpoints are added to the graph automatically.	required
`order`	`Literal['create', 'drop']`	`"create"` for dependencies before dependents, `"drop"` for dependents before dependencies.	`'create'`

Returns:

Type	Description
`DependencySortResult`	Ordered objects plus cycle diagnostics if cycles prevented a complete order.

sort_ddl_results ¶

sort_ddl_results(ddl_results, *, order='create', raise_on_cycles=True)

Sort DDL result objects by their typed dependency edges.

Parameters:

Name	Type	Description	Default
`ddl_results`	`Iterable[DDLResult]`	DDL payloads to order.	required
`order`	`Literal['create', 'drop']`	`"create"` or `"drop"` dependency direction.	`'create'`
`raise_on_cycles`	`bool`	Raise `DependencyCycleError` instead of returning a partial order.	`True`

Returns:

Type	Description
`DDLResult`	DDL results in dependency order. Results not represented in the sorted
`...`	graph are appended in their original order.

GeezerVison

Data Dictionary¶

Loader & Dialect Registry¶

DataDictionaryLoader ¶

get_data_dictionary_loader ¶

get_dialect_config ¶

list_registered_dialects ¶

normalize_dialect_name ¶

register_dialect ¶

Schema & Catalog Metadata Types¶

VersionInfo ¶

TableMetadata ¶

ColumnMetadata ¶

ColumnProfileMetadata ¶

IndexMetadata ¶

ForeignKeyMetadata ¶

ConstraintMetadata ¶

ViewMetadata ¶

RoutineMetadata ¶

TriggerMetadata ¶

DDLResult ¶

Capability Profiles & Result Envelopes¶

DialectConfig ¶

MetadataCapabilityProfile ¶

MetadataResult ¶

SystemMetadataRequest ¶

SystemMetadataResult ¶

Dependency Graph & Topological Sorting¶

DependencyEdge ¶

DependencySortResult ¶

dependency_edges_from_foreign_keys ¶

dependency_edges_from_metadata ¶

sort_dependencies ¶

sort_ddl_results ¶