boti-data 1.3.1__tar.gz → 1.3.3__tar.gz

{boti_data-1.3.1 → boti_data-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boti-data
-Version: 1.3.1
+Version: 1.3.3
 Summary: Data infrastructure for the Boti ecosystem
 Author: Luis Valverde
 Maintainer-email: Luis Valverde <lvalverdeb@gmail.com>

{boti_data-1.3.1 → boti_data-1.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boti-data"
-version = "1.3.1"
+version = "1.3.3"
 description = "Data infrastructure for the Boti ecosystem"
 readme = "README.md"
 requires-python = ">=3.13"

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/__init__.py

@@ -63,6 +63,7 @@ __all__ = [
     "SqlModelRegistry",
     "SqlRepository",
     "SqlUnitOfWork",
+    "TableDescription",
     "TrueExpr",
     "VectorMetric",
     "WatermarkStore",
@@ -70,6 +71,7 @@ __all__ = [
     "align_frames_for_join",
     "apply_schema_map",
     "available_sinks",
+    "awrite_parquet",
     "build_incremental_filters",
     "create_sink",
     "ensure_greenlet_available",
@@ -83,6 +85,7 @@ __all__ = [
     "register_sink",
     "validate_schema",
     "vector_distance",
+    "write_parquet",
 ]
 
 # Every public name is loaded lazily (PEP 562) so that importing boti_data (or
@@ -132,6 +135,7 @@ _LAZY = {
     "SqlLoadRequest": ("boti_data.gateway", "SqlLoadRequest"),
     "DataFrameOptions": ("boti_data.gateway", "DataFrameOptions"),
     "DataFrameParams": ("boti_data.gateway", "DataFrameParams"),
+    "TableDescription": ("boti_data.gateway", "TableDescription"),
     "DataHelper": ("boti_data.helper", "DataHelper"),
     "indexed_left_join": ("boti_data.joins", "indexed_left_join"),
     "left_join_frames": ("boti_data.joins", "left_join_frames"),
@@ -161,8 +165,10 @@ _LAZY = {
     "SinkRegistry": ("boti_data.pipelines", "SinkRegistry"),
     "SinkWriteResult": ("boti_data.pipelines", "SinkWriteResult"),
     "available_sinks": ("boti_data.pipelines", "available_sinks"),
+    "awrite_parquet": ("boti_data.pipelines", "awrite_parquet"),
     "create_sink": ("boti_data.pipelines", "create_sink"),
     "register_sink": ("boti_data.pipelines", "register_sink"),
+    "write_parquet": ("boti_data.pipelines", "write_parquet"),
     "FileWatermarkStore": ("boti_data.watermark", "FileWatermarkStore"),
     "FsspecWatermarkStore": ("boti_data.watermark", "FsspecWatermarkStore"),
     "IncrementalResult": ("boti_data.watermark", "IncrementalResult"),
@@ -172,6 +178,12 @@ _LAZY = {
 }
 
 
+# Deliberately identical to the __getattr__ in boti_data/db/__init__.py and
+# boti_data/parquet/__init__.py -- this is PEP 562's own documented
+# module-level lazy-import boilerplate. Each copy needs its own private
+# _LAZY dict/globals()/__name__, so sharing an implementation would need an
+# awkward globals()-passing helper for no real gain over these 6 lines.
+# spaghetti-ignore[duplicate-function-body]: see above
 def __getattr__(name: str) -> Any:
     if name in _LAZY:
         module_name, attr = _LAZY[name]

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/db/__init__.py

@@ -63,6 +63,12 @@ _LAZY = {
 }
 
 
+# Deliberately identical to the __getattr__ in boti_data/__init__.py and
+# boti_data/parquet/__init__.py -- this is PEP 562's own documented
+# module-level lazy-import boilerplate. Each copy needs its own private
+# _LAZY dict/globals()/__name__, so sharing an implementation would need an
+# awkward globals()-passing helper for no real gain over these 6 lines.
+# spaghetti-ignore[duplicate-function-body]: see above
 def __getattr__(name: str) -> Any:
     if name in _LAZY:
         module_name, attr = _LAZY[name]

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/db/arrow_schema_mapper.py

@@ -274,6 +274,37 @@ def build_empty_arrow_table(schema: pa.Schema) -> pa.Table:
     return pa.Table.from_arrays(arrays, schema=schema)
 
 
+def arrow_table_from_pylist_with_fallback(
+    rows: list[dict[str, Any]],
+    columns: list[str],
+) -> pa.Table:
+    """Build a Table from raw dict rows with no SQLAlchemy schema to guide it.
+
+    Used for raw-SQL-text loads, where there is no ``Select`` statement to
+    derive column types from, so pyarrow must infer everything from the
+    Python values themselves. A column of otherwise-uniform values pyarrow's
+    inference can't place (``uuid.UUID``, ``decimal.Decimal``, ...) fails the
+    *entire* table with an opaque ``ArrowInvalid`` naming the value, never the
+    column. Isolate any such column and fall back to stringifying just that
+    column instead of failing the whole load.
+    """
+    try:
+        return pa.Table.from_pylist(rows)
+    except (pa.ArrowInvalid, pa.ArrowTypeError):
+        _logger.debug("Whole-table inference failed, falling back to per-column coercion")
+
+    arrays: dict[str, pa.Array] = {}
+    for column in columns:
+        values = [row.get(column) for row in rows]
+        try:
+            arrays[column] = pa.array(values)
+        except (pa.ArrowInvalid, pa.ArrowTypeError):
+            arrays[column] = pa.array(
+                [str(value) if value is not None else None for value in values]
+            )
+    return pa.Table.from_pydict(arrays)
+
+
 # ---------------------------------------------------------------------------
 # Arrow → pandas conversion with type preservation
 # ---------------------------------------------------------------------------

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/db/sql_config.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-import warnings
 from pathlib import Path
 from typing import Any, Union
 
+from boti.core.logger import Logger
 from boti.core.models import ResourceConfig
 from boti.core.security import is_valid_env_var_name
 from boti.core.settings import SqlDatabaseSettings, load_prefixed_model
@@ -18,7 +18,19 @@ _ALLOWED_POOLCLASS_IMPORTS = {
 
 
 class SqlDatabaseConfig(ResourceConfig):
-    """Immutable configuration for SQLAlchemy engine initialization."""
+    """Immutable configuration for SQLAlchemy engine initialization.
+
+    ``query_only=True`` enforces read-only access at the database level (via
+    a ``SET ... READ ONLY``-style statement issued on the SQLAlchemy
+    ``"connect"`` event, not just by blocking ORM methods in Python) — this
+    assumes ``connection_url`` points directly at Postgres/MySQL, or at a
+    *session*-pooling-mode connection pooler (one physical backend connection
+    dedicated to one logical client for its whole lifetime). It does **not**
+    cover a *transaction*-pooling-mode pooler (e.g. PgBouncer in ``transaction``
+    mode): there, a single physical connection can be handed to a different,
+    unrelated logical client between transactions, and session-level state set
+    once at physical-connect time is not guaranteed to survive that handoff.
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
@@ -27,7 +39,9 @@ class SqlDatabaseConfig(ResourceConfig):
         default=True,
         description=(
             "When true, native database-enforced read-only access is required. "
-            "Set explicitly to false to allow writes."
+            "Set explicitly to false to allow writes. Assumes a direct connection "
+            "or a session-pooling-mode proxy — transaction-pooling-mode poolers "
+            "(e.g. PgBouncer 'transaction' mode) are out of scope; see class docstring."
         ),
     )
     worker_connection_env_var: str | None = Field(
@@ -148,11 +162,9 @@ class WorkerSqlConfig(BaseModel):
         if config.worker_connection_env_var is not None:
             payload["connection_env_var"] = config.worker_connection_env_var
         else:
-            warnings.warn(
+            Logger.default_logger(logger_name=cls.__name__).warning(
                 "worker_connection_env_var is not set; falling back to raw DSN. "
-                "Credentials may be visible in scheduler logs.",
-                UserWarning,
-                stacklevel=2,
+                "Credentials may be visible in scheduler logs."
             )
             payload["connection_url"] = config.connection_url
         return cls(**payload)

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/db/sql_model_registry.py

@@ -238,22 +238,34 @@ class SqlModelRegistry:
         md = self._get_or_create_metadata(ekey, schema)
         md_lock = self._get_or_create_md_lock(md_key)
         qname = self._qualified_key(schema, tname)
-        tbl = self._reflect_table(engine, md, md_lock, qname=qname, tname=tname, schema=schema)
-
-        context = ModelBuildContext(
-            qname=qname,
-            tname=tname,
-            base_class=base_class,
-            module_label=module_label,
-            prefer_stable_names=prefer_stable_names,
-            ekey=ekey,
-            schema=schema,
-            missing_pk_warning_suffix="Ensure ORM mutation sequences validate bounds manually.",
-        )
-        model_cls = self._resolve_or_build_model(tbl, qname, context, target_label="DB target")
-        with self._lock:
-            self._model_cache[model_key] = model_cls
-        return model_cls
+
+        # The whole reflect -> resolve-or-build -> cache-write sequence must
+        # be one atomic unit per md_key: reflection alone was already
+        # serialized via md_lock, but resolve-or-build and the cache write
+        # previously ran outside it, so two concurrent first-accesses for the
+        # same table could both pass "does a mapped class already exist?"
+        # before either finished building — each got a distinct Python class
+        # mapped to the same Table.
+        with md_lock:
+            cached = self._check_cache(model_key, refresh=False)
+            if cached is not None:
+                return cached
+
+            tbl = self._reflect_table(engine, md, qname=qname, tname=tname, schema=schema)
+            context = ModelBuildContext(
+                qname=qname,
+                tname=tname,
+                base_class=base_class,
+                module_label=module_label,
+                prefer_stable_names=prefer_stable_names,
+                ekey=ekey,
+                schema=schema,
+                missing_pk_warning_suffix="Ensure ORM mutation sequences validate bounds manually.",
+            )
+            model_cls = self._resolve_or_build_model(tbl, qname, context, target_label="DB target")
+            with self._lock:
+                self._model_cache[model_key] = model_cls
+            return model_cls
 
     async def get_model_async(
         self,
@@ -278,26 +290,33 @@ class SqlModelRegistry:
         md = self._get_or_create_metadata(ekey, schema)
         md_lock = await self._get_or_create_md_lock_async(md_key)
         qname = self._qualified_key(schema, tname)
-        tbl = await self._reflect_table_async(
-            engine, md, md_lock, qname=qname, tname=tname, schema=schema
-        )
 
-        context = ModelBuildContext(
-            qname=qname,
-            tname=tname,
-            base_class=base_class,
-            module_label=module_label,
-            prefer_stable_names=prefer_stable_names,
-            ekey=ekey,
-            schema=schema,
-            missing_pk_warning_suffix="Ensure Async ORM validation sequences capture bounds correctly.",
-        )
-        model_cls = self._resolve_or_build_model(
-            tbl, qname, context, target_label="Async DB target"
-        )
-        async with self._async_lock:
-            self._model_cache[model_key] = model_cls
-        return model_cls
+        # See get_model()'s comment: the whole sequence must be one atomic
+        # unit per md_key, not just the reflection step.
+        async with md_lock:
+            cached = await self._check_cache_async(model_key, refresh=False)
+            if cached is not None:
+                return cached
+
+            tbl = await self._reflect_table_async(
+                engine, md, qname=qname, tname=tname, schema=schema
+            )
+            context = ModelBuildContext(
+                qname=qname,
+                tname=tname,
+                base_class=base_class,
+                module_label=module_label,
+                prefer_stable_names=prefer_stable_names,
+                ekey=ekey,
+                schema=schema,
+                missing_pk_warning_suffix="Ensure Async ORM validation sequences capture bounds correctly.",
+            )
+            model_cls = self._resolve_or_build_model(
+                tbl, qname, context, target_label="Async DB target"
+            )
+            async with self._async_lock:
+                self._model_cache[model_key] = model_cls
+            return model_cls
 
     def _resolve_or_build_model(
         self,
@@ -335,12 +354,15 @@ class SqlModelRegistry:
 
     # Not a copy-pasted twin: sync md.reflect() vs conn.run_sync(md.reflect) is
     # a genuine concurrency-primitive difference (see get_model()'s comment above).
+    # Both callers (get_model/get_model_async) already hold this md_key's
+    # md_lock/md_async_lock for the whole reflect -> resolve-or-build -> cache
+    # sequence, so no locking happens here — acquiring the same (non-reentrant)
+    # lock again inside would deadlock.
     @staticmethod
     # spaghetti-ignore[sync-async-duplication]: see above
     def _reflect_table(
         engine: Engine,
         md: MetaData,
-        md_lock: threading.Lock,
         *,
         qname: str,
         tname: str,
@@ -348,18 +370,14 @@ class SqlModelRegistry:
     ) -> Table | None:
         tbl = md.tables.get(qname)
         if tbl is None:
-            with md_lock:
-                tbl = md.tables.get(qname)
-                if tbl is None:
-                    md.reflect(bind=engine, only=[tname], schema=schema)
-                tbl = md.tables.get(qname)
+            md.reflect(bind=engine, only=[tname], schema=schema)
+            tbl = md.tables.get(qname)
         return tbl
 
     @staticmethod
     async def _reflect_table_async(
         engine: AsyncEngine,
         md: MetaData,
-        md_lock: asyncio.Lock,
         *,
         qname: str,
         tname: str,
@@ -367,12 +385,9 @@ class SqlModelRegistry:
     ) -> Table | None:
         tbl = md.tables.get(qname)
         if tbl is None:
-            async with md_lock:
-                tbl = md.tables.get(qname)
-                if tbl is None:
-                    async with engine.begin() as conn:
-                        await conn.run_sync(md.reflect, only=[tname], schema=schema)
-                tbl = md.tables.get(qname)
+            async with engine.begin() as conn:
+                await conn.run_sync(md.reflect, only=[tname], schema=schema)
+            tbl = md.tables.get(qname)
         return tbl
 
     def clear(self) -> None:

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/gateway/__init__.py

@@ -2,7 +2,13 @@ from boti_data.db import AsyncSqlDatabaseResource
 
 from .core import DataGateway
 from .policies import GatewayPolicies
-from .requests import DataFrameOptions, DataFrameParams, ParquetLoadRequest, SqlLoadRequest
+from .requests import (
+    DataFrameOptions,
+    DataFrameParams,
+    ParquetLoadRequest,
+    SqlLoadRequest,
+    TableDescription,
+)
 
 __all__ = [
     "AsyncSqlDatabaseResource",
@@ -12,4 +18,5 @@ __all__ = [
     "GatewayPolicies",
     "ParquetLoadRequest",
     "SqlLoadRequest",
+    "TableDescription",
 ]

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/gateway/_backend_strategies.py

@@ -50,6 +50,7 @@ from .requests import (
     BackendResource,
     ResolvedExecutionMode,
     ReturnType,
+    TableDescription,
 )
 
 _log = logging.getLogger(__name__)
@@ -244,6 +245,33 @@ class BackendStrategy(ABC):
         """
         return self.estimate_result_size(ctx)
 
+    # -- Schema/row-count discovery ------------------------------------------
+
+    def describe(
+        self,
+        resource: BackendResource | None,
+        table: str,
+        *,
+        row_count_limit: int,
+    ) -> TableDescription:
+        """Cheaply inspect *table*'s schema and an approximate row count.
+
+        Raises ``NotImplementedError`` by default — only backends with a
+        cheap, bounded introspection path (no full-table load) should
+        override this.
+        """
+        raise NotImplementedError(f"{self.name} backend does not support describe().")
+
+    async def describe_async(
+        self,
+        resource: BackendResource | None,
+        table: str,
+        *,
+        row_count_limit: int,
+    ) -> TableDescription:
+        """Async variant of :meth:`describe`. Default delegates to the sync method."""
+        return self.describe(resource, table, row_count_limit=row_count_limit)
+
 
 # ---------------------------------------------------------------------------
 # Registry

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/gateway/core.py

@@ -14,7 +14,7 @@ from boti.core.lifecycle import LifecycleCore
 from boti.core.lifecycle_pickle import PicklableLifecycleCoreMixin
 from boti_dask import async_safe_head, safe_head
 
-from . import core_load
+from . import core_describe, core_load
 from ._gateway_init import (
     GatewayInitOptions,
     build_gateway_from_backend,
@@ -31,6 +31,7 @@ from .requests import (
     ExecutionMode,
     ResolvedReturnType,
     ReturnType,
+    TableDescription,
 )
 
 
@@ -246,6 +247,31 @@ class DataGateway(PicklableLifecycleCoreMixin, LifecycleCore):
         )
         return await async_safe_head(frame, n=n, npartitions=npartitions)
 
+    def describe(
+        self, table: str | None = None, *, row_count_limit: int = 10_000
+    ) -> TableDescription:
+        """Cheaply inspect a table's schema and an approximate row count.
+
+        Runs a bounded introspection query — reflecting column dtypes without
+        loading any rows, then counting up to *row_count_limit* rows — instead
+        of requiring callers to know to self-impose ``limit=`` on a full
+        :meth:`load` before exploring an unfamiliar table.
+
+        Args:
+            table: DB table name. Defaults to the table configured at
+                construction time (configured mode).
+            row_count_limit: Row count is exact up to this many rows; beyond
+                it, :attr:`TableDescription.row_count_is_exact` is ``False``
+                and :attr:`TableDescription.row_count` reports this cap.
+        """
+        return core_describe.describe(self, table, row_count_limit=row_count_limit)
+
+    async def adescribe(
+        self, table: str | None = None, *, row_count_limit: int = 10_000
+    ) -> TableDescription:
+        """Async variant of :meth:`describe`."""
+        return await core_describe.describe_async(self, table, row_count_limit=row_count_limit)
+
     def load(self, **options: Any) -> FrameResult:
         """Load data from the configured backend.
 

boti_data-1.3.3/src/boti_data/gateway/core_describe.py

@@ -0,0 +1,45 @@
+"""DataGateway.describe()/adescribe() implementations.
+
+Split out of core.py purely for line-count headroom, mirroring core_load.py's
+split: DataGateway's public methods keep their docstrings and stay callable
+exactly as before, but their bodies move here as free functions taking the
+gateway instance explicitly.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .requests import TableDescription
+
+if TYPE_CHECKING:
+    from .core import DataGateway
+
+
+def resolve_describe_table(gateway: DataGateway, table: str | None) -> str:
+    resolved = table or gateway._table
+    if resolved is None:
+        raise ValueError(
+            "describe()/adescribe() require table= (or a table configured at construction time)."
+        )
+    return resolved
+
+
+# Not a copy-pasted twin: both are thin delegates to
+# gateway._strategy.describe()/describe_async() after the identical
+# table-resolution step; the real logic lives one layer down (sql_describe.py).
+# spaghetti-ignore[sync-async-duplication]: see above
+def describe(gateway: DataGateway, table: str | None, *, row_count_limit: int) -> TableDescription:
+    resolved_table = resolve_describe_table(gateway, table)
+    return gateway._strategy.describe(
+        gateway.resource, resolved_table, row_count_limit=row_count_limit
+    )
+
+
+async def describe_async(
+    gateway: DataGateway, table: str | None, *, row_count_limit: int
+) -> TableDescription:
+    resolved_table = resolve_describe_table(gateway, table)
+    return await gateway._strategy.describe_async(
+        gateway.resource, resolved_table, row_count_limit=row_count_limit
+    )

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/gateway/loaders.py

@@ -14,6 +14,7 @@ from boti_data.db import (
     SqlPartitionedLoadRequest,
 )
 from boti_data.db.arrow_schema_mapper import (
+    arrow_table_from_pylist_with_fallback,
     arrow_table_to_pandas,
     build_arrow_schema_from_sqlalchemy_types,
     rows_to_arrow_table,
@@ -61,10 +62,15 @@ def _arrow_table_from_sql_result(
     *,
     statement: Any | None,
 ) -> pa.Table:
-    if statement is None:
+    # A raw-SQL-text load's statement is a SQLAlchemy TextClause, which has no
+    # .selected_columns (that's Select-only) -- treat it the same as no
+    # statement at all rather than letting the attribute lookup below crash.
+    if statement is None or not hasattr(statement, "selected_columns"):
         if not rows:
             return pa.table({name: [] for name in columns})
-        return pa.Table.from_pylist([dict(zip(columns, row)) for row in rows])
+        return arrow_table_from_pylist_with_fallback(
+            [dict(zip(columns, row)) for row in rows], columns
+        )
 
     sql_types = [getattr(selected, "type", None) for selected in statement.selected_columns]
     schema = build_arrow_schema_from_sqlalchemy_types(columns, sql_types)

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/gateway/requests.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any, Literal, Union
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
@@ -207,3 +208,18 @@ class ParquetLoadRequest(BaseModel):
                 "Use as_pandas=True, return_type='arrow', or apply Dask head()/partitions explicitly."
             )
         return self
+
+
+@dataclass(frozen=True, slots=True)
+class TableDescription:
+    """Result of :meth:`~boti_data.gateway.core.DataGateway.describe`.
+
+    ``row_count`` is exact when ``row_count_is_exact`` is ``True``; otherwise
+    it reports the ``row_count_limit`` cap that was hit, meaning "at least
+    this many rows" rather than the real total.
+    """
+
+    table: str
+    columns: dict[str, str]
+    row_count: int
+    row_count_is_exact: bool

boti_data-1.3.3/src/boti_data/gateway/sql_describe.py

@@ -0,0 +1,41 @@
+"""Cheap SQL table introspection backing DataGateway.describe()/adescribe().
+
+Split out of sql_strategy.py purely for line-count headroom, mirroring the
+sql_size_estimation.py module split.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from boti_data.db.partitioned_planner import SqlPartitionPlanner
+from boti_data.db.partitioned_statements import infer_meta_dtypes
+
+from .loaders import reflect_and_select
+from .requests import TableDescription
+
+
+def describe_table(
+    resource: Any,
+    table: str,
+    *,
+    row_count_limit: int,
+) -> TableDescription:
+    """Reflect *table*'s columns and count rows up to *row_count_limit*.
+
+    Never loads any actual row data: column dtypes come from SQLAlchemy
+    reflection (no query executed), and the row count is a single bounded
+    ``COUNT(*)`` subquery capped at *row_count_limit* rows — safe to run
+    against an unfamiliar table without risking an accidental unbounded
+    query against a large production table.
+    """
+    _model, statement = reflect_and_select(resource, table)
+    columns = infer_meta_dtypes(statement)
+    counted = SqlPartitionPlanner(resource).count_rows_up_to(statement, row_count_limit)
+    is_exact = counted <= row_count_limit
+    return TableDescription(
+        table=table,
+        columns=columns,
+        row_count=counted if is_exact else row_count_limit,
+        row_count_is_exact=is_exact,
+    )

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/gateway/sql_strategy.py

@@ -34,7 +34,8 @@ from .frame_strategies import FrameResult
 from .loaders import build_sql_partitioned_request, read_sql_async
 from .normalization import build_partitioned_load_options
 from .planning import InChunkPolicy
-from .requests import BackendConfig, BackendName, BackendResource, SqlLoadRequest
+from .requests import BackendConfig, BackendName, BackendResource, SqlLoadRequest, TableDescription
+from .sql_describe import describe_table
 from .sql_partitioned_exec import run_async_partitioned_request
 from .sql_size_estimation import (
     _DEFAULT_PARTITION_CHUNK_SIZE,
@@ -376,3 +377,32 @@ class SqlAlchemyStrategy(BackendStrategy):
                 return await asyncio.to_thread(self.estimate_result_size, ctx)
             return await estimate_configured_async(ctx)
         return await estimate_structured_async(ctx)
+
+    # -- Schema/row-count discovery ------------------------------------------
+
+    def describe(
+        self,
+        resource: BackendResource | None,
+        table: str,
+        *,
+        row_count_limit: int,
+    ) -> TableDescription:
+        if resource is None:
+            raise ValueError("describe() requires an active SQL resource.")
+        return describe_table(resource, table, row_count_limit=row_count_limit)
+
+    # describe() is already a single quick, bounded query -- offloading it to
+    # a thread (like estimate_result_size_async's sync-resource branch above)
+    # is enough; no separate async reflection/count path is worth the
+    # duplication for something this cheap.
+    # spaghetti-ignore[sync-async-duplication]: see above
+    async def describe_async(
+        self,
+        resource: BackendResource | None,
+        table: str,
+        *,
+        row_count_limit: int,
+    ) -> TableDescription:
+        return await asyncio.to_thread(
+            self.describe, resource, table, row_count_limit=row_count_limit
+        )

{boti_data-1.3.1 → boti_data-1.3.3}/src/boti_data/helper.py

@@ -10,7 +10,7 @@ from boti_dask import DaskSession, dask_session
 
 from boti_data.gateway import DataGateway
 from boti_data.gateway.incremental import IncrementalLoadService
-from boti_data.gateway.requests import BackendConfig
+from boti_data.gateway.requests import BackendConfig, TableDescription
 from boti_data.joins import indexed_left_join, left_join_frames
 from boti_data.schema import DataFrameLike
 from boti_data.watermark.incremental import IncrementalResult
@@ -273,6 +273,20 @@ class DataHelper(PicklableLifecycleCoreMixin, LifecycleCore):
     async def apreview(self, statement: Any, model: Any, n: int = 5, **options: Any) -> Any:
         return await self.gateway.aload(**self._build_preview_options(statement, model, n, options))
 
+    # Not a copy-pasted twin: pure delegate to self.gateway.describe()/
+    # adescribe() with identical kwargs, matching this class's other
+    # unflagged proxy pairs (load/aload, preview/apreview).
+    # spaghetti-ignore[sync-async-duplication]: see above
+    def describe(
+        self, table: str | None = None, *, row_count_limit: int = 10_000
+    ) -> TableDescription:
+        return self.gateway.describe(table, row_count_limit=row_count_limit)
+
+    async def adescribe(
+        self, table: str | None = None, *, row_count_limit: int = 10_000
+    ) -> TableDescription:
+        return await self.gateway.adescribe(table, row_count_limit=row_count_limit)
+
     def load_period(self, dt_field: str, start: str, end: str, **kwargs: Any) -> Any:
         return self.gateway.load_period(dt_field, start, end, **kwargs)