refactor(kernel): simplify metadata filter forwarding

Author: vuanhphung

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Release History
 
 # Unreleased
-- Kernel metadata filters now preserve empty strings as empty patterns, matching no catalogs, schemas, tables, or columns. Only `None` leaves a filter unset; `%` and `*` retain their existing wildcard behavior (PECOBLR-4221).
+- Kernel metadata filters now preserve empty strings, matching no catalogs, schemas, tables, or columns. Only `None` leaves a filter unset; other values retain their exact-identifier or pattern semantics (PECOBLR-4221).
 - Kernel backend (`use_kernel=True`): OAuth **M2M with a JWT private-key client assertion** (RFC 7523) is now supported. Pass `oauth_client_id` + `oauth_jwt_key_file` + `oauth_jwt_kid` (with optional `oauth_jwt_passphrase` for an encrypted PKCS#8 key, `oauth_jwt_algorithm` defaulting to `RS256`, `oauth_scopes`, and `token_url` for the IdP token endpoint) and the connector routes them to the kernel's `auth_type="oauth-m2m-jwt"`, which signs a short-lived assertion with the private key instead of sending a client secret. The kernel owns the token lifecycle. A private-key file is treated as unambiguous JWT M2M intent and is mutually exclusive with `oauth_client_secret` / `credentials_provider` (both raise `NotSupportedError`). Verified end-to-end against an Azure Databricks workspace with the service principal's public certificate registered on its Entra ID app registration. Requires `databricks-sql-kernel >= 0.2.0` with JWT support.
 - Kernel backend (`use_kernel=True`): OAuth U2M with `auth_type="databricks-oauth"` now forwards the connector's `databricks-sql-python` OAuth-app bundle (`client_id` + `sql offline_access` scopes + redirect port) into the kernel, so a bare U2M connection authenticates as `databricks-sql-python` — parity with the Thrift path — instead of inheriting the kernel's own `databricks-sql-connector` default. A caller-supplied `oauth_client_id` (with its coupled `oauth_redirect_port`) is honored, as is a caller-supplied `oauth_scopes`; absent one, the connector default (`sql offline_access`) is forwarded. Note: the kernel binds a single U2M redirect port, so unlike the Thrift path (which tries the full `8020..8024` range) the kernel path uses only one port and does not fall back to the next port if it is already bound — pass `oauth_redirect_port` (with `oauth_client_id`) to pick a free one on a port collision (PECOBLR-4040)
 - Kernel backend (`use_kernel=True`): **Azure Entra (Azure AD) service-principal M2M is now supported.** `auth_type="azure-sp-m2m"` forwards `azure_client_id` / `azure_client_secret`; the kernel is the Azure-aware auth core — it builds the Entra v2.0 token endpoint and the `{app_id}/.default` scope, and **auto-discovers the tenant** from the workspace's `/aad/auth` redirect when `azure_tenant_id` is omitted (matching Thrift). The `Authorization` bearer is the Databricks-audience data token, which alone authenticates a workspace-member SP. Set `azure_workspace_resource_id` and the kernel also sends the Azure SP management token (`X-Databricks-Azure-SP-Management-Token`) + `X-Databricks-Azure-Workspace-Resource-Id` header (matching the JDBC driver), so a service principal with an Azure RBAC role but no workspace membership can authenticate; omit it and no ARM management-scope token is fetched. Azure AD **U2M** (`auth_type="azure-oauth"`) now routes to the kernel's OAuth U2M flow, identically to `auth_type="databricks-oauth"`: the kernel runs the in-house workspace-federated browser flow, which Azure workspaces support (the workspace federates login to Entra). It forwards the connector's `databricks-sql-python` OAuth app, not the Thrift Azure app (`96eecda7` / port 8030), which is registered for Thrift's direct-Entra flow the kernel does not perform (PECOBLR-4141; PECOBLR-4120)

src/databricks/sql/backend/databricks_client.py

@@ -248,7 +248,7 @@ def get_schemas(
             max_rows: Maximum number of rows to fetch in a single batch
             max_bytes: Maximum number of bytes to fetch in a single batch
             cursor: The cursor object that will handle the results
-            catalog_name: Optional catalog name pattern to filter by. ``None``
+            catalog_name: Optional exact catalog name to filter by. ``None``
                 leaves the filter unset; an empty string matches nothing.
             schema_name: Optional schema name pattern to filter by. ``None``
                 leaves the filter unset; an empty string matches nothing.
@@ -327,7 +327,7 @@ def get_columns(
             max_rows: Maximum number of rows to fetch in a single batch
             max_bytes: Maximum number of bytes to fetch in a single batch
             cursor: The cursor object that will handle the results
-            catalog_name: Optional catalog name pattern to filter by. ``None``
+            catalog_name: Optional exact catalog name to filter by. ``None``
                 leaves the filter unset; an empty string matches nothing.
             schema_name: Optional schema name pattern to filter by. ``None``
                 leaves the filter unset; an empty string matches nothing.

src/databricks/sql/backend/kernel/client.py

@@ -117,36 +117,13 @@ def _is_not_found(exc: BaseException) -> bool:
     )
 
 
-def _catalog_or_none(value: Optional[str]) -> Optional[str]:
-    """Map all-catalog wildcards to the kernel's unfiltered representation.
-
-    This makes ``columns(catalog='%')`` behave like
-    ``tables(catalog='%')`` / ``schemas(catalog='%')`` — the kernel
-    treats the catalog as an exact identifier for SHOW COLUMNS. ``None``
-    remains the only absent filter. Other strings must be preserved as real
-    filters; in particular, an empty string matches nothing just as it does
-    on the Thrift backend. Non-empty whitespace-only strings remain invalid
-    and are left for kernel validation.
-    """
-    if value is None or value in ("%", "*"):
-        return None
-    return value
-
-
 def _exact_catalog_and_pattern(
     catalog: Optional[str], pattern: Optional[str]
 ) -> Tuple[Optional[str], Optional[str]]:
-    """Adapt an empty exact catalog to an empty subordinate pattern.
-
-    At ``KERNEL_REV``, ``Identifier("")`` is invalid while
-    ``LikePattern("")`` means match-nothing. Schema and column metadata
-    take an exact catalog, so represent an empty catalog as all catalogs
-    constrained by an empty schema pattern. This preserves empty-catalog
-    semantics without passing an invalid identifier to the kernel.
-    """
+    """Avoid constructing the kernel's invalid empty ``Identifier``."""
     if catalog == "":
         return None, ""
-    return _catalog_or_none(catalog), pattern
+    return catalog, pattern
 
 
 def _is_staging_statement(operation: str) -> bool:
@@ -966,7 +943,7 @@ def get_tables(
             # do the work — no connector-side drain + refilter. Passing it
             # through preserves streaming for large schemas.
             stream = self._kernel_session.metadata().list_tables(
-                catalog=_catalog_or_none(catalog_name),
+                catalog=catalog_name,
                 schema_pattern=schema_name,
                 table_pattern=table_name,
                 table_types=table_types if table_types else None,

src/databricks/sql/client.py

@@ -1577,8 +1577,8 @@ def schemas(
         """
         Get schemas corresponding to the catalog_name and schema_name.
 
-        ``None`` leaves a filter unset. An empty string is a real empty
-        pattern and matches nothing. Names can contain % wildcards.
+        ``None`` leaves a filter unset and an empty string matches nothing.
+        ``catalog_name`` is exact; ``schema_name`` can contain % wildcards.
         :returns self
         """
         self._check_not_closed()
@@ -1604,8 +1604,8 @@ def tables(
         """
         Get tables corresponding to the catalog_name, schema_name and table_name.
 
-        ``None`` leaves a filter unset. An empty string is a real empty
-        pattern and matches nothing. Names can contain % wildcards.
+        ``None`` leaves a filter unset and an empty string matches nothing.
+        Names can contain % wildcards.
         :returns self
         """
         self._check_not_closed()
@@ -1634,8 +1634,8 @@ def columns(
         """
         Get columns corresponding to the catalog_name, schema_name, table_name and column_name.
 
-        ``None`` leaves a filter unset. An empty string is a real empty
-        pattern and matches nothing. Names can contain % wildcards.
+        ``None`` leaves a filter unset and an empty string matches nothing.
+        ``catalog_name`` is exact; other names can contain % wildcards.
 
         ``catalog_name=None`` is accepted on all backends and matches
         columns across every catalog (the kernel issues ``SHOW COLUMNS``

tests/unit/test_kernel_client.py

@@ -1564,9 +1564,8 @@ def test_sync_execute_leaves_rowcount_default_when_num_modified_rows_none():
 # ---------------------------------------------------------------------------
 
 
-@pytest.mark.parametrize("wildcard", ["%", "*"])
-def test_get_columns_normalizes_wildcard_catalog_to_none(wildcard):
-    """The kernel represents the supported all-catalog wildcards as ``None``."""
+@pytest.mark.parametrize("exact_catalog", ["%", "*"])
+def test_get_columns_preserves_exact_catalog(exact_catalog):
     c = _make_client()
     c._kernel_session = MagicMock()
     list_columns = c._kernel_session.metadata.return_value.list_columns
@@ -1580,14 +1579,14 @@ def test_get_columns_normalizes_wildcard_catalog_to_none(wildcard):
         max_rows=1,
         max_bytes=1,
         cursor=cursor,
-        catalog_name=wildcard,
+        catalog_name=exact_catalog,
         schema_name="s",
         table_name="t",
         column_name="c",
     )
 
     list_columns.assert_called_once_with(
-        catalog=None,
+        catalog=exact_catalog,
         schema_pattern="s",
         table_pattern="t",
         column_pattern="c",