feat: align geospatial support configuration

Signed-off-by: Cathleen Yan <58714163+cathleeny@users.noreply.github.com>

Author: cathleeny

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Release History
 
 # Unreleased
-- Add the kernel-only `geospatial_as_string` connection option. GEOMETRY / GEOGRAPHY results are exposed as EWKT strings when true or `{"srid": int, "wkb": bytes}` values when false.
+- Add the default-enabled, kernel-only `enable_geospatial_support` connection option. GEOMETRY / GEOGRAPHY results are exposed as `{"srid": int, "wkb": bytes}` values when true or WKT / EWKT strings when false.
 
 # 4.6.0 (2026-09-24)
 - Upgrade Databricks SQL Kernel to 1.1.0; the kernel dependency is now stable and no longer experimental.

CONNECTION_PARAMETERS.md

@@ -153,7 +153,7 @@ to change without notice.
 | `max_download_threads`                | `int`  |   ✅   |   ❌   | `10`          | Worker threads for cloud-fetch downloads. Not forwarded to the kernel.                                        |
 | `enable_query_result_lz4_compression` | `bool` |   ✅   |   ❌   | `True`        | LZ4-compress result payloads. Not forwarded; the kernel handles compression internally.                       |
 | `_disable_pandas`                     | `bool` |   ✅   |   ✅   | `False`       | Skip the pandas-based Arrow→row deserialization and materialize rows directly with PyArrow. This is a **Python-side** result-conversion toggle, not a wire option: the kernel returns results as Arrow (`RecordBatch`es) and the connector runs the *same* `_convert_arrow_table` for both backends, so the flag is honored on the kernel path too. Affects only row fetches (`fetchone`/`fetchmany`/`fetchall`); the `fetch*_arrow` methods return the Arrow table unchanged regardless of this flag. |
-| `geospatial_as_string`                | `bool \| None` |   ❌   |   ✅   | `None` (kernel default: `True`) | Return GEOMETRY / GEOGRAPHY as EWKT strings when `True`, or as `{"srid": int, "wkb": bytes}` values when `False`. `None` leaves the kernel default in force. This is a local result conversion and is never forwarded to SEA. |
+| `enable_geospatial_support`           | `bool` |   ❌   |   ✅   | `True` | Return GEOMETRY / GEOGRAPHY as `{"srid": int, "wkb": bytes}` values when `True`, or as WKT / EWKT strings when `False`. This is a local result conversion and is never forwarded to SEA. |
 | `_use_arrow_native_complex_types`     | `bool` |   ✅   |   ✅   | `True`        | Return `ARRAY`/`MAP`/`STRUCT` as native Arrow types instead of JSON strings. Forwarded to the kernel.         |
 | `_use_arrow_native_decimals`          | `bool` |   ✅   |   ❌   | `True`        | Thrift wire encoding for `DECIMAL`: `True` → native Arrow `decimal128`, `False` → Arrow string. **No value-level effect**, though: the connector unconditionally re-casts the column back to `decimal128` (`convert_decimals_in_arrow_table`, `thrift_backend.py`), so both `fetchall()` and `fetchall_arrow()` yield `Decimal` / `decimal128(p,s)` either way (verified live). Not forwarded to the kernel, which always returns native Arrow decimals. |
 | `_use_arrow_native_timestamps`        | `bool` |   ✅   |   ❌   | `True`        | Thrift wire encoding for `TIMESTAMP`: `True` → native Arrow timestamp (→ Python `datetime`), `False` → Arrow string (→ Python **`str`**). **Unlike decimals there is no re-cast**, so `False` genuinely surfaces strings — and `cursor.description` still reports the type code as `'timestamp'`, a mismatch to watch for (verified live). Note the connector always also sends the `spark.thriftserver.arrowBasedRowSet.timestampAsString=false` conf, but the `timestampAsArrow=False` flag wins. Not forwarded to the kernel, which always returns native Arrow timestamps. |

KERNEL_REV

@@ -1 +1 @@
-ad3bc6993bca95b810839feade77ccd0ab98ece5
+b7e9310b27be16a6c42490e58c4b5c4a525320bc

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

@@ -169,27 +169,25 @@ def _kernel_session_accepts_kwarg(name: str) -> bool:
     return name in params
 
 
-def _kernel_geospatial_kwargs(value: Optional[bool]) -> Dict[str, bool]:
-    """Build the optional geospatial result-representation kwarg.
+def _kernel_geospatial_kwargs(value: bool) -> Dict[str, bool]:
+    """Build the default-enabled native geospatial-support kwarg.
 
-    ``None`` deliberately omits the option so the installed kernel owns its
-    default. An explicit value must never be silently ignored: older kernel
-    wheels do not declare ``geospatial_as_string`` and would otherwise return a
-    different public value shape than the caller requested.
+    The value is always passed explicitly so the driver and kernel contracts
+    cannot drift. Older kernel wheels do not declare
+    ``enable_geospatial_support`` and must fail clearly rather than silently
+    return a different public value shape.
     """
-    if value is None:
-        return {}
     if not isinstance(value, bool):
         raise ValueError(
-            "geospatial_as_string must be a bool or None; "
+            "enable_geospatial_support must be a bool; "
             f"got {type(value).__name__}"
         )
-    if not _kernel_session_accepts_kwarg("geospatial_as_string"):
+    if not _kernel_session_accepts_kwarg("enable_geospatial_support"):
         raise NotSupportedError(
-            "geospatial_as_string requires a newer databricks-sql-kernel "
+            "enable_geospatial_support requires a newer databricks-sql-kernel "
             "wheel that exposes geospatial result representation support."
         )
-    return {"geospatial_as_string": value}
+    return {"enable_geospatial_support": value}
 
 
 def _kernel_telemetry_kwargs(options: Dict[str, Any]) -> Dict[str, Any]:
@@ -285,12 +283,14 @@ def __init__(
         # The kernel binding owns type and range validation.
         self._request_timeout_secs = kwargs.get("request_timeout_secs")
         self._max_connections = kwargs.get("max_connections")
-        # Client-side result representation for GEOMETRY / GEOGRAPHY. None
-        # leaves the kernel default in force (EWKT strings); False requests the
-        # canonical Arrow struct and surfaces as ``{"srid": int, "wkb":
-        # bytes}`` through pyarrow. This is intentionally separate from
-        # ``session_configuration``: it is never forwarded to SEA.
-        self._geospatial_as_string = kwargs.get("geospatial_as_string")
+        # Default-enabled native GEOMETRY / GEOGRAPHY support. True requests
+        # the canonical Arrow struct and surfaces as ``{"srid": int, "wkb":
+        # bytes}`` through pyarrow; False requests WKT / EWKT strings. This is
+        # intentionally separate from ``session_configuration``: it is never
+        # forwarded to SEA.
+        self._enable_geospatial_support = kwargs.get(
+            "enable_geospatial_support", True
+        )
         # Kernel telemetry phase 7 adds binding/runtime identity and
         # telemetry config kwargs directly to ``databricks_sql_kernel.Session``.
         self._telemetry_options = kwargs.get("telemetry_options") or {}
@@ -408,7 +408,9 @@ def open_session(
             # kernel's ``retry_*`` kwargs. Empty when at defaults.
             retry_kwargs = _kernel_retry_kwargs(self._retry_options)
             telemetry_kwargs = _kernel_telemetry_kwargs(self._telemetry_options)
-            geospatial_kwargs = _kernel_geospatial_kwargs(self._geospatial_as_string)
+            geospatial_kwargs = _kernel_geospatial_kwargs(
+                self._enable_geospatial_support
+            )
             max_connections_kwargs: Dict[str, Any] = {}
             if _kernel_session_accepts_kwarg("max_connections"):
                 max_connections_kwargs["max_connections"] = self._max_connections

src/databricks/sql/client.py

@@ -194,13 +194,12 @@ def __init__(
                 decision. This is an intentional divergence from the
                 Thrift/SEA paths, where an explicit ``True`` can still
                 be suppressed by the feature flag.
-            :param geospatial_as_string: `bool | None`, optional (default is None)
+            :param enable_geospatial_support: `bool`, optional (default is True)
                 Kernel backend only. Controls the public representation of
                 ``GEOMETRY`` and ``GEOGRAPHY`` result values. ``True`` returns
-                EWKT strings (for example ``"SRID=4326;POINT(1 2)"``);
-                ``False`` returns ``{"srid": int, "wkb": bytes}``; and
-                ``None`` uses the kernel default (currently EWKT strings).
-                The conversion is local to the kernel/driver and this option is
+                ``{"srid": int, "wkb": bytes}``; ``False`` returns WKT / EWKT
+                strings (for example ``"SRID=4326;POINT(1 2)"``). The
+                conversion is local to the kernel/driver and this option is
                 never sent to the SQL Execution API.
             :param use_hybrid_disposition: `bool`, optional (default is False)
                 Use the hybrid disposition instead of the inline disposition.

src/databricks/sql/session.py

@@ -314,7 +314,9 @@ def _create_backend(
                 retry_options=kernel_retry_options,
                 request_timeout_secs=kwargs.get("_socket_timeout"),
                 max_connections=kwargs.get("_pool_maxsize") or None,
-                geospatial_as_string=kwargs.get("geospatial_as_string"),
+                enable_geospatial_support=kwargs.get(
+                    "enable_geospatial_support", True
+                ),
                 telemetry_options=kernel_telemetry_options,
             )
 

tests/unit/test_kernel_client.py

@@ -392,14 +392,14 @@ def fake_session(**kw):
     assert captured["max_connections"] == max_connections
 
 
-@pytest.mark.parametrize("as_string", [True, False])
+@pytest.mark.parametrize("enabled", [True, False])
 def test_open_session_passes_geospatial_representation_to_kernel(
-    monkeypatch, as_string
+    monkeypatch, enabled
 ):
     captured = {}
 
-    def fake_session(*, geospatial_as_string=None, **kw):
-        captured["geospatial_as_string"] = geospatial_as_string
+    def fake_session(*, enable_geospatial_support=True, **kw):
+        captured["enable_geospatial_support"] = enable_geospatial_support
         sess = MagicMock()
         sess.session_id = "sess-id"
         return sess
@@ -410,15 +410,15 @@ def fake_session(*, geospatial_as_string=None, **kw):
         http_path="/sql/1.0/warehouses/abc",
         auth_provider=AccessTokenAuthProvider("dapi-test"),
         ssl_options=None,
-        geospatial_as_string=as_string,
+        enable_geospatial_support=enabled,
     )
 
     c.open_session(session_configuration=None, catalog=None, schema=None)
 
-    assert captured["geospatial_as_string"] is as_string
+    assert captured["enable_geospatial_support"] is enabled
 
 
-def test_open_session_omits_unset_geospatial_representation(monkeypatch):
+def test_open_session_enables_geospatial_support_by_default(monkeypatch):
     captured = {}
 
     def fake_session(**kw):
@@ -437,7 +437,7 @@ def fake_session(**kw):
 
     c.open_session(session_configuration=None, catalog=None, schema=None)
 
-    assert "geospatial_as_string" not in captured
+    assert captured["enable_geospatial_support"] is True
 
 
 def test_open_session_rejects_explicit_geospatial_option_with_old_kernel(
@@ -468,15 +468,15 @@ def fake_session_without_geospatial(
         http_path="/sql/1.0/warehouses/abc",
         auth_provider=AccessTokenAuthProvider("dapi-test"),
         ssl_options=None,
-        geospatial_as_string=False,
+        enable_geospatial_support=False,
     )
 
     with pytest.raises(NotSupportedError, match="newer databricks-sql-kernel"):
         c.open_session(session_configuration=None, catalog=None, schema=None)
 
 
 def test_geospatial_option_rejects_non_bool():
-    with pytest.raises(ValueError, match="must be a bool or None"):
+    with pytest.raises(ValueError, match="must be a bool"):
         kernel_client._kernel_geospatial_kwargs("false")
 
 
@@ -578,6 +578,7 @@ def fake_session_without_optional_kwargs(
         catalog=None,
         schema=None,
         session_conf=None,
+        enable_geospatial_support=True,
         complex_types_as_json=False,
         intervals_as_string=False,
         request_timeout_secs=None,

tests/unit/test_session.py

@@ -476,7 +476,7 @@ def test_retry_and_socket_timeout_threaded_into_kernel_client(self):
                 _retry_stop_after_attempts_duration=600.0,
                 _socket_timeout=12.5,
                 _pool_maxsize=41,
-                geospatial_as_string=False,
+                enable_geospatial_support=False,
             )
             try:
                 _, kwargs = mock_kernel_client.call_args
@@ -487,7 +487,7 @@ def test_retry_and_socket_timeout_threaded_into_kernel_client(self):
                 assert opts["retry_stop_after_attempts_duration"] == 600.0
                 assert kwargs["request_timeout_secs"] == 12.5
                 assert kwargs["max_connections"] == 41
-                assert kwargs["geospatial_as_string"] is False
+                assert kwargs["enable_geospatial_support"] is False
             finally:
                 conn.close()
 
@@ -793,6 +793,18 @@ def test_connect_use_kernel_instantiates_real_kernel_backend(self):
             finally:
                 conn.close()
 
+    def test_enable_geospatial_support_matches_real_kernel_signature(self):
+        self._real_kernel_or_skip()
+
+        from databricks.sql.backend.kernel.client import _kernel_geospatial_kwargs
+
+        assert _kernel_geospatial_kwargs(True) == {
+            "enable_geospatial_support": True
+        }
+        assert _kernel_geospatial_kwargs(False) == {
+            "enable_geospatial_support": False
+        }
+
 
 class TestReydenThriftFallback:
     """Transparent auto-recovery from a Reyden / Real-Time warehouse rejecting