feat: detect GeoArrow columns in PyArrow tables

[kirangadhave]

Summary

Detect GeoArrow extension metadata on PyArrow tables as the geometry semantic type (MO-6362).

The generic NarwhalsTableManager formats geometry cells in to_json_str and preserves PyArrow field metadata through apply_formatting. Existing host guards (search, sort, stats, top-k, unique values) activate via _geometry_columns with no new guard code.

GeoPandas and pandas tables are unchanged; they continue to use PandasTableManager overrides from #10536.

No frontend changes.

🗺️ Stack

This PR is part of a four-PR stack that adds a semantic geometry type for geospatial columns (MO-6362). Merge bottom-up with squash. Each PR targets the branch below it, so each diff shows only its own commits. After each merge, I rebase the remaining PRs.

1. test: add geometry fixture corpus and baselines #10516: geometry fixture corpus and ordinary-table baselines
2. feat: add GeoPandas geometry table support #10536: geometry contract and GeoPandas detection
3. feat: detect GeoArrow columns in PyArrow tables #10558: PyArrow adapter (GeoArrow field metadata) ⬅️ this PR
4. feat: detect duckdb spatial columns as geometry #10592: DuckDB adapter and SQL metadata (completes the release gate)

ibis detection is deferred: no user demand, and nothing downstream depends on it.

Important

Release gate: do not include this PR in a marimo release until #10592 also merges.

Closes MO-7324

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview	Aug 20, 2026 8:05pm

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[Copilot]

Pull request overview

This PR extends marimo’s table geometry support to PyArrow-backed (Narwhals) tables by detecting GeoArrow extension metadata and treating those columns as the geometry semantic type, ensuring correct serialization and operation-guard behavior.

Changes:

• Detect GeoArrow geometry columns in PyArrow tables by reading ARROW:extension:name field metadata (geoarrow.*, ogc.wkb).
• Format geometry cells during NarwhalsTableManager.to_json_str() (WKB → placeholder; WKT/objects → capped text) while preserving schema metadata across apply_formatting().
• Add/update characterization and contract tests covering detection, formatting, and guard behavior (search/top-k/unique/stats).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
tests/_plugins/ui/_impl/tables/test_geometry.py	Adds PyArrow/GeoArrow detection + manager behavior tests (serialization + operation guards).
tests/_plugins/ui/_impl/tables/test_geometry_fixtures.py	Updates GeoArrow characterization expectations to geometry semantic type.
marimo/_plugins/ui/_impl/tables/narwhals_table.py	Formats geometry cells in JSON output and changes formatting application to preserve PyArrow field metadata.
marimo/_plugins/ui/_impl/tables/geometry.py	Adds PyArrow GeoArrow detection via field extension metadata parsing.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cubic-dev-ai]

All reported issues were addressed across 4 files

Architecture diagram

sequenceDiagram
    participant UI as Marimo UI
    participant TM as Table Manager
    participant NTM as NarwhalsTableManager
    participant GEO as Geometry Utils
    participant NW as Narwhals Frame
    participant PA as PyArrow Table

    Note over UI,PA: GeoArrow Column Detection and Formatting Flow

    UI->>TM: Request table data
    TM->>NTM: get_field_types()
    
    NTM->>GEO: find_geometry_columns(frame)
    GEO->>NW: Check implementation type
    
    alt PyArrow implementation
        NW-->>GEO: is_pyarrow() = true
        GEO->>PA: Get schema fields
        PA-->>GEO: Field metadata
        
        loop For each field
            GEO->>GEO: Read ARROW:extension:name
            alt geoarrow.wkb or ogc.wkb
                GEO->>GEO: Set encoding = "wkb"
            else geoarrow.wkt
                GEO->>GEO: Set encoding = "wkt"
            else geoarrow.* prefix
                GEO->>GEO: Set encoding = "other"
            else Non-geo extension
                GEO->>GEO: Skip column
            end
        end
        
        GEO-->>NTM: Geometry column map
        NTM-->>TM: Field types with "geometry" semantic
    else Pandas implementation
        NW-->>GEO: is_pandas() = true
        GEO->>GEO: Use Pandas-specific detection
        GEO-->>NTM: Geometry column map
        NTM-->>TM: Field types with "geometry" semantic
    end

    Note over UI,PA: Table JSON Serialization Flow
    
    UI->>TM: Get table data (to_json_str)
    TM->>NTM: to_json_str()
    
    NTM->>NTM: Apply formatting if mapping
    
    alt Format mapping provided
        NTM->>NW: Apply column formatting
        loop For each formatted column
            NTM->>NW: Create new series
            NW->>PA: with_columns()
            PA-->>NW: Updated table with preserved metadata
        end
    end
    
    NTM->>NW: Get rows as named dicts
    NW-->>NTM: Row data with raw geometry values
    
    alt Geometry columns found
        loop For each row
            loop For each column
                alt Is geometry column
                    NTM->>GEO: format_geometry_cell(value, encoding)
                    alt WKB encoding
                        GEO->>GEO: Generate placeholder with byte size
                    else WKT encoding
                        GEO->>GEO: Pass through text, cap length
                    else Other encoding
                        GEO->>GEO: Skip or minimal formatting
                    end
                    GEO-->>NTM: Formatted geometry value
                end
            end
        end
    end
    
    NTM->>NTM: sanitize_json_bigint()
    NTM-->>UI: JSON string with formatted geometry

    Note over UI,PA: Downstream Operations
    
    UI->>TM: Search / sort / stats request
    TM->>NTM: Operation on geometry column
    
    NTM->>GEO: Check _geometry_columns
    
    alt Search on geometry
        NTM-->>TM: Skip search (0 results)
    else Top-K on geometry
        NTM-->>TM: Return empty list
    else Unique values on geometry
        NTM-->>TM: Return empty list
    else Stats on geometry
        NTM->>PA: Count total and nulls
        PA-->>NTM: Stats with unique = null
        NTM-->>TM: Stats summary
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>