feat: add native metadata statistics

docs/reference/adapters/adbc.rst

@@ -231,3 +231,57 @@ Data Dictionary
 .. autoclass:: sqlspec.adapters.adbc.data_dictionary.AdbcDataDictionary
    :members:
    :show-inheritance:
+
+Native Metadata And Statistics
+==============================
+
+``AdbcDataDictionary`` keeps SQLSpec's central dialect data-dictionary queries
+as the canonical fallback. It detects the database behind the ADBC connection
+and uses the same dialect query registry as the native adapter when ADBC
+metadata is unsupported, incomplete, or too broad. The standardized ADBC
+metadata APIs (``adbc_get_objects``, ``adbc_get_table_schema``) are an optional
+overlay when the driver returns complete table, column, and foreign-key
+payloads that can be normalized to SQLSpec's public metadata types.
+
+``get_statistics`` is separate from the shared data dictionary surface because
+SQLSpec does not define a portable SQL statistics contract. It wraps
+``adbc_get_statistics`` directly; unsupported drivers raise
+:exc:`sqlspec.exceptions.OperationalError`.
+
+.. list-table:: ADBC native metadata support (driver manager 1.11.0)
+   :header-rows: 1
+
+   * - Backend
+     - Metadata behavior
+     - Statistics behavior
+   * - PostgreSQL
+     - Native overlay when available; central PostgreSQL SQL fallback
+     - Native (approximate; run ``ANALYZE`` for fresh estimates)
+   * - SQLite
+     - Native overlay when available; central SQLite SQL fallback
+       (type names populated; nullability unreliable)
+     - Unsupported (raises ``OperationalError``)
+   * - DuckDB
+     - Native overlay for single tables when schema enrichment succeeds;
+       schema-wide column listings use central DuckDB SQL
+     - Unsupported (raises ``OperationalError``)
+   * - Flight SQL / GizmoSQL
+     - Native overlay is server dependent; central dialect fallback applies
+       when the backend dialect is mapped
+     - Server dependent
+   * - BigQuery
+     - Central BigQuery SQL fallback
+     - Unverified
+
+Precision limits:
+
+- ADBC native name filters are SQL ``LIKE`` patterns; SQLSpec post-filters
+  native results by exact table name, but schema filters containing ``_`` or
+  ``%`` may match more broadly on the server side before fallback.
+- The SQLite driver reports ``xdbc_is_nullable`` as ``YES`` even for
+  ``NOT NULL`` columns.
+- Index metadata always uses SQL introspection; ADBC GetObjects has no
+  portable index representation.
+- ``get_statistics`` maps the standard ADBC statistic keys 0-6 to their
+  canonical names (``adbc.statistic.row_count`` and friends); driver-specific
+  keys are reported numerically.

docs/reference/adapters/arrow_odbc.rst

@@ -35,3 +35,15 @@ Data Dictionary
 .. autoclass:: sqlspec.adapters.arrow_odbc.data_dictionary.ArrowOdbcDataDictionary
    :members:
    :show-inheritance:
+
+Schema Discovery
+================
+
+``ArrowOdbcDataDictionary.get_columns`` first uses bundled dialect catalog
+queries. When no query exists for the detected dialect (or it returns no
+rows) and a table name is given, the driver issues a zero-row probe
+(``SELECT * FROM "schema"."table" WHERE 1=0``) and derives column names,
+ordering, nullability, and SQL type names from the Arrow reader schema.
+Arrow-derived type names are approximations (for example ``VARCHAR`` for any
+string column); ``mssql_python`` and other ODBC adapters without native
+metadata APIs remain SQL-only.