yggdrasil.databricks.schema.schemas

schemas

Collection-level service for Unity Catalog schemas.

Provides __getitem__, schema(), table(), catalog(), find(), and list() against the Databricks catalog API. Per-resource DDL/DML lives in :class:~yggdrasil.databricks.schema.schema.Schema.

Hierarchy

::

client.schemas                               # Schemas (root)
client.schemas(catalog_name="main")          # Schemas scoped to "main"
client.schemas["main.sales"]                 # Schema  (fully qualified)
client.schemas["sales"]                      # Schema  (uses default catalog)
client.schemas["main.sales.orders"]          # Table
client.schemas["main.sales.orders.price"]    # Column
client.schemas.list()                        # Iterator[Schema]
client.schemas.list(catalog_name="main")     # Iterator[Schema] in "main"

Caching strategy

A module-level :class:ExpiringDict (_SCHEMA_INFO_CACHE) keyed by "host|catalog.schema" acts as a local cache (TTL = 5 min by default).

Schemas

Schemas(
    client=None, catalog_name: str | None = None, schema_name: str | None = None
)

Bases: DatabricksService

Collection-level service for Unity Catalog schemas.

Attach a default catalog_name (and optional schema_name) so callers don't have to repeat them on every call::

schemas = client.schemas(catalog_name="main")

# navigate by subscript
schema = schemas["sales"]                    # Schema ("main.sales")
schema = schemas["main.sales"]               # Schema  (fully qualified)
table  = schemas["main.sales.orders"]        # Table

# explicit factory methods
schema  = schemas.schema("main.sales")       # Schema
table   = schemas.table("main.sales.orders") # Table
catalog = schemas.catalog("main")            # Catalog

# list
for sch in schemas.list():
    for tbl in sch.tables():
        ...

wheels property

wheels: 'Wheels'

Wheel registry service (shorthand for client.wheels).

environments property

environments: 'Environments'

Base-environment service (shorthand for client.environments).

tables property

tables: 'Tables'

Collection-level Unity Catalog table service (shorthand for client.tables).

views property

views: 'Tables'

Alias for :attr:tables — :class:Table covers both managed/external tables and view-shaped securables.

catalogs property

catalogs: 'Catalogs'

Collection-level Unity Catalog hierarchy service (shorthand for client.catalogs).

schemas property

schemas: 'Schemas'

Collection-level Unity Catalog schema service (shorthand for client.schemas).

volumes property

volumes: 'Volumes'

Collection-level Unity Catalog volume service (shorthand for client.volumes).

genie property

genie: 'Genie'

Genie service (shorthand for client.genie).

ai property

ai: 'DatabricksAI'

Databricks AI umbrella service (shorthand for client.ai).

schema

schema(
    location: "UCSchema | str | None" = None,
    *,
    catalog_name: str | None = None,
    schema_name: str | None = None
) -> UCSchema

Return a :class:UCSchema bound to this service.

Uses the module-level cache when available.

Parameters:

Name	Type	Description	Default
location	'UCSchema | str | None'	Two-part dotted "catalog.schema" name (optional if catalog_name / schema_name are provided).	None
catalog_name	str | None	Override catalog (falls back to self.catalog_name).	None
schema_name	str | None	Override schema (falls back to self.schema_name).	None

table

table(
    location: str | None = None,
    *,
    catalog_name: str | None = None,
    schema_name: str | None = None,
    table_name: str | None = None
) -> Table

Return a :class:Table via the client-level tables service.

Parameters:

Name	Type	Description	Default
location	str | None	Three-part dotted name "catalog.schema.table" (or fewer parts, filled by service defaults).	None
catalog_name	str | None	Override catalog.	None
schema_name	str | None	Override schema.	None
table_name	str | None	Override table.	None

catalog

catalog(name: str | None = None) -> UCCatalog

Return a :class:Catalog using this service's client.

Parameters:

Name	Type	Description	Default
name	str | None	Catalog name (falls back to self.catalog_name).	None

list

list(
    name: str | None = None,
    *,
    catalog_name: str | None = None,
    use_cache: bool = True
) -> Iterator[UCSchema]

Iterate over visible schemas, optionally scoped to a catalog.

Parameters:

Name	Type	Description	Default
name	str | None	Optional schema-name filter. When it contains *, matching uses a case-insensitive glob (e.g. "sales_*", "*_raw", "*").	None
catalog_name	str | None	Catalog to list (falls back to self.catalog_name). When None the iteration fans out across every visible catalog. When it contains * the iteration fans out across catalogs matching the glob.	None
use_cache	bool	Populate _SCHEMA_INFO_CACHE from results.	True

find_remote

find_remote(
    catalog_name: str, schema_name: str, *, raise_error: bool = True
) -> Optional[SchemaInfo]

Raw API lookup — GET by fully-qualified name, no cache.

Returns None on miss when raise_error=False.

find

find(
    location: str | None = None,
    *,
    catalog_name: str | None = None,
    schema_name: str | None = None,
    raise_error: bool = True,
    cache_ttl: float | None = 300.0
) -> Optional[UCSchema]

Resolve a schema by name.

Caching is controlled by cache_ttl. Set cache_ttl=None to bypass the cache for this lookup.

Parameters:

Name	Type	Description	Default
location	str | None	Two-part dotted "catalog.schema" name.	None
catalog_name	str | None	Override catalog (falls back to service default).	None
schema_name	str | None	Override schema (falls back to service default).	None
raise_error	bool	Raise :exc:ResourceDoesNotExist when not found.	True
cache_ttl	float | None	Entry TTL in seconds (None → bypass cache).	300.0

parse_location

parse_location(
    location: str | None = None,
    *,
    catalog_name: str | None = None,
    schema_name: str | None = None
) -> tuple[Optional[str], Optional[str]]

Parse a 1- or 2-part dotted name into (catalog, schema).

Keyword overrides take precedence over parts extracted from location. Service defaults fill any remaining blanks.

invalidate

invalidate(
    schema: UCSchema | str | None = None,
    *,
    catalog_name: Optional[str] = None,
    schema_name: Optional[str] = None
) -> None

Evict one entry from the module-level schema-info cache.

invalidate_all classmethod

invalidate_all() -> None

Clear the entire module-level schema-info cache.

default_tags

default_tags(update: bool = True) -> dict[str, str]

Return default resource tags for Databricks assets.

Returns:

Type	Description
dict[str, str]	A dict of default tags.