Data Dictionary¶

from sqlspec.data_dictionary import (
    ColumnMetadata,
    DataDictionaryLoader,
    DDLResult,
    DependencySortResult,
    DialectConfig,
    ForeignKeyMetadata,
    IndexMetadata,
    MetadataCapabilityProfile,
    MetadataResult,
    TableMetadata,
    VersionInfo,
    get_data_dictionary_loader,
    get_dialect_config,
    list_registered_dialects,
    sort_ddl_results,
    sort_dependencies,
)

Cross-database catalog introspection metadata, capability profiles, dialect registry, and foreign-key topological sorting. Access runtime introspection through driver.data_dictionary on any SyncDriverAdapterBase or AsyncDriverAdapterBase session.

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)

Register a dialect configuration.

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 (`a`/`ALWAYS` or `d`/`BY DEFAULT`), if applicable.
`sequence_name`	`str \| None`	Backing sequence name owned by a serial or identity column.
`is_generated`	`bool \| int`	Whether the column is a computed or virtual/stored generated 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.

ForeignKeyMetadata ¶

Metadata for a foreign key constraint.

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.

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.