Data Dictionary

SQLSpec's data dictionary provides structured database metadata discovery across supported adapters. It reports what each adapter can inspect, returns capability details with every metadata lookup, and represents database objects with typed result models.

Metadata Contract

The data dictionary uses structured metadata envelopes:

  • MetadataCapabilityProfile reports support by domain and adapter.

  • MetadataCapability distinguishes supported, unsupported, unknown, and not implemented domains.

  • MetadataResult wraps every domain lookup, including unsupported domains, so callers never need to guess whether an empty list means "nothing exists" or "the database cannot answer this".

  • Object detail models carry an ObjectIdentity with catalog, schema, object name, object type, dialect, quoted name, and source.

  • DDL lookups return a DDLResult with native/generated/hybrid/lossy status.

Applications should inspect MetadataResult.capability before using MetadataResult.items.

Capability Vocabulary

The stable support values are:

  • supported

  • unsupported

  • unknown

  • not_implemented

The stable fidelity values are:

  • native

  • generated

  • hybrid

  • lossy

  • partial

  • transport_fallback

Risk gates describe why metadata may be hidden, expensive, or unavailable: privileged, billed, expensive, license_gated, redacted, managed_service_limited, extension_required, and version_gated.

Usage

Use capabilities first:

profile = db.data_dictionary.get_metadata_capabilities(db)
tables = profile.get("tables")

if tables.support == "supported":
    result = db.data_dictionary.get_table_details(db, "users")
    for item in result.items:
        ...

For unsupported domains, SQLSpec returns a structured result:

result = db.data_dictionary.get_privileges(db, "users")
if result.capability.support == "unsupported":
    ...

System and performance metadata is disabled by default unless the adapter chapter explicitly opts into a safe, redacted, privilege-aware implementation.