`yggdrasil.databricks.sql.sql_utils`¶

sql_utils ¶

Shared SQL string helpers for the Databricks SQL package.

safe_table_name ¶

safe_table_name(
    name: str | None, *, limit: int = MAX_TABLE_NAME_LEN
) -> str | None

Return name unchanged if it fits, otherwise truncate + hash.

Databricks Unity Catalog caps identifiers at 255 chars. When a caller hands in something longer, split name on common separators (space, underscore, dash), keep as many leading tokens as fit alongside a BLAKE2b digest of the overflow tail, and join the result with _. Tokens are kept whole — no chopping in the middle of a word — so layer/role qualifiers (raw, brz, curated, dim, …) stay readable at the front of the truncated name.

The result fits the limit, stays stable for the same input, and uses only identifier-safe ASCII. None and empty strings pass through unchanged so this stays safe to call before defaults have been resolved.

is_glob_pattern ¶

is_glob_pattern(value: Any) -> bool

Return True when value is a string carrying a * wildcard.

name_matcher ¶

name_matcher(pattern: str | None) -> Optional[Callable[[str | None], bool]]

Build a predicate for filtering resource names with optional globbing.

None → None (caller skips filtering entirely).
No * → exact-match predicate (case-sensitive).
Contains * → case-insensitive :func:fnmatch.fnmatchcase predicate.

The predicate accepts None defensively and treats it as an empty name.

normalize_databricks_collation ¶

normalize_databricks_collation(collation: str | None) -> str | None

Normalize and validate a Databricks collation name.

Databricks supports the built-in UNICODE*, UTF8_BINARY*, and UTF8_LCASE* families plus ICU locale collations with optional _CI, _AI, and _RTRIM suffixes.

databricks_tag_literal ¶

databricks_tag_literal(
    value: Any, *, collation: str | None = DEFAULT_TAG_COLLATION
) -> str

Build a SQL string literal for Databricks tag DDL.

Tag keys and values can be annotated with an explicit collation to avoid dependence on the session or object default collation.

escape_sql_string ¶

escape_sql_string(s: str) -> str

Escape a Python string for safe embedding in a single-quoted SQL literal.

quote_ident ¶

quote_ident(ident: str) -> str

Quote a SQL identifier using backticks, escaping embedded backticks.

quote_qualified_ident ¶

quote_qualified_ident(name: str) -> str

Backtick-quote each segment of a dotted identifier.

quote_principal ¶

quote_principal(name: str) -> str

Backtick-quote a Databricks principal name as a single identifier.

requalify_table_refs ¶

requalify_table_refs(
    text: str,
    *,
    source: tuple[str | None, str | None],
    target: tuple[str | None, str | None]
) -> str

Rewrite catalog.schema table-reference prefixes in SQL text.

Used when cloning a view to a new schema: the source's stored view_definition keeps pointing at the source catalog/schema, so the clone must re-point the inner query at the target. source / target are (catalog, schema) tuples.

Rewrites, on identifier boundaries (so a longer name that merely contains the catalog/schema as a substring is left alone), both quoting styles:

a 3-part prefix <src_cat>.<src_sch>. → ``tgt_cat`.`tgt_sch`.``
a bare 2-part prefix <src_sch>. (catalog implied by the view's home) → ``tgt_sch`.— but never thesegment of a *different* catalog's 3-part name (it's guarded by the leading-boundary lookbehind, which rejects a preceding.`` / backtick).

Returns text unchanged when source == target (or either is missing a schema). This is deliberately textual — it does not parse the SQL — so it preserves the definition verbatim apart from the requalified prefixes.

sql_literal ¶

sql_literal(value: Any) -> str

Convert a Python value into a Databricks SQL literal string.

yggdrasil.databricks.sql.sql_utils¶