yggdrasil.databricks.catalog.catalogs

catalogs

Collection-level service for Unity Catalog catalogs and schemas.

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

Hierarchy

::

client.catalogs["main"]                            # Catalog
client.catalogs["main"]["sales"]                   # Schema
client.catalogs["main.sales"]                      # Schema  (dot-separated shorthand)
client.catalogs["main"]["sales"]["orders"]         # Table
client.catalogs["main.sales.orders"]               # Table
client.catalogs["main"]["sales"]["orders"]["price"]  # Column
client.catalogs["main.sales.orders.price"]         # Column
client.catalogs.list_catalogs()                    # Iterator[Catalog]

Caching strategy

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

Catalogs

Catalogs(client: Optional[DatabricksClient] = None)

Bases: DatabricksService

Collection-level service for Unity Catalog catalogs and schemas.

Provides a dict-like interface for the full UC hierarchy::

catalogs = client.catalogs

# navigate by subscript — each step returns the next level
catalog = catalogs["main"]                            # Catalog
schema  = catalogs["main"]["sales"]                   # Schema
table   = catalogs["main"]["sales"]["orders"]         # Table
column  = catalogs["main"]["sales"]["orders"]["price"]  # Column

# shorthand dot-notation string
schema  = catalogs["main.sales"]                      # Schema
table   = catalogs["main.sales.orders"]               # Table
column  = catalogs["main.sales.orders.price"]         # Column

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

# list
for cat in catalogs.list_catalogs():
    for sch in cat.schemas():
        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).

catalog

catalog(name: str) -> UCCatalog

Return a :class:Catalog bound to this service.

Uses the module-level cache when available.

Parameters:

Name	Type	Description	Default
name	str	Catalog name.	required

schema

schema(full_name: str) -> UCSchema

Return a :class:Schema from a "catalog.schema" string.

Parameters:

Name	Type	Description	Default
full_name	str	Two-part dotted name (backtick-quoting is stripped).	required

table

table(location: str) -> Table

Return a :class:Table from a three-part fully-qualified name.

Parameters:

Name	Type	Description	Default
location	str	Three-part dotted name "catalog.schema.table".	required

list_catalogs

list_catalogs(
    name: str | None = None, *, use_cache: bool = True
) -> Iterator[UCCatalog]

Iterate over visible catalogs, populating the local cache.

Parameters:

Name	Type	Description	Default
name	str | None	Optional catalog-name filter. When it contains *, matching uses a case-insensitive glob (e.g. "prod_*", "*_raw", "*"). Without * it's an exact match.	None
use_cache	bool	Populate _CATALOG_INFO_CACHE from results.	True

parse_location

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

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

Keyword overrides take precedence over parts extracted from location.

invalidate_all classmethod

invalidate_all() -> None

Clear the entire module-level catalog-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.