feat: GeoArrow export — GEOGRAPHY/GEOMETRY as geoarrow.wkb

[jatorre]

Summary

Adds geospatial export support: GEOGRAPHY/GEOMETRY columns are automatically tagged with geoarrow.wkb Arrow extension metadata, enabling DuckDB and other Arrow consumers to receive native geometry types.

How it works

1. WKB output format — Sets GEOGRAPHY_OUTPUT_FORMAT=WKB and GEOMETRY_OUTPUT_FORMAT=WKB at connection time so geo columns arrive as binary WKB (not GeoJSON strings)
2. Geo column detection — Before executing a query, extracts the table name and runs DESCRIBE TABLE to identify GEOGRAPHY/GEOMETRY columns. Catalog metadata correctly reports the original type regardless of output format.
3. geoarrow.wkb tagging — Tags identified columns in the Arrow schema with ARROW:extension:name = "geoarrow.wkb". GEOGRAPHY gets CRS EPSG:4326 (always WGS84). GEOMETRY gets no CRS (see TODOs).
4. Zero conversion overhead — Data arrives as binary WKB and passes through unchanged (identCol).

Schema mapping

Snowflake type	Arrow type	Extension	CRS
GEOGRAPHY	Binary	geoarrow.wkb	EPSG:4326
GEOMETRY	Binary	geoarrow.wkb	(empty — see TODO)

Why DESCRIBE TABLE?

Snowflake's REST API reports geo columns as "type": "binary" in rowtype response metadata when WKB output format is set, losing the original type information. Both rowtype and DESCRIBE RESULT are affected. Only DESCRIBE TABLE (catalog metadata) preserves the original type. We've reported this limitation to Snowflake.

TODOs

1. GEOMETRY SRID — Requires inspecting data to determine SRID, which needs first-batch buffering. Same cross-driver challenge as adbc-drivers/redshift#2 and adbc-drivers/databricks#350. Fixed CRS for GEOGRAPHY (always 4326), empty CRS for GEOMETRY.

2. Arbitrary queries — Currently only table scans (SELECT ... FROM table) trigger geo detection. Complex queries (joins, subqueries, CTEs) won't get geoarrow metadata. The data is still correct WKB, just without the Arrow extension type annotation.

Test results

End-to-end against real Snowflake:

• GEOGRAPHY columns read as DuckDB native GEOMETRY('EPSG:4326') ✓
• Points, lines, polygons all correct ✓
• GeoParquet export preserves GEOMETRY type with CRS ✓
• Non-geo queries unaffected ✓

Related

• Import PR: feat: GeoArrow support for bulk ingestion (GEOGRAPHY/GEOMETRY) #99
• Redshift SRID issue: adbc-drivers/redshift#2
• Databricks geoarrow: adbc-drivers/databricks#350

🤖 Generated with Claude Code

[jatorre]

cc @sfc-gh-obielov — We've reported to Snowflake that the REST API rowtype metadata loses the original column type (geography/geometry) when GEOGRAPHY_OUTPUT_FORMAT or GEOMETRY_OUTPUT_FORMAT is set to WKB/EWKB. Both rowtype and DESCRIBE RESULT report "binary" instead of the original type. Only DESCRIBE TABLE (catalog metadata) preserves it.

This is why this PR needs an extra DESCRIBE TABLE query before execution — to identify which columns are actually GEOGRAPHY/GEOMETRY. If Snowflake preserved the original type in rowtype metadata regardless of output format (or added a sourceType/databaseType field), the extra query would be unnecessary and we could support arbitrary queries, not just table scans.

[lidavidm]

@zeroshade is there an upstream feature request/bug report we can reference for this?

[lidavidm]

Suggested change

	wkb := "WKB"
	if _, ok := d.cfg.Params["GEOGRAPHY_OUTPUT_FORMAT"]; !ok {
	d.cfg.Params["GEOGRAPHY_OUTPUT_FORMAT"] = &wkb
	}
	if _, ok := d.cfg.Params["GEOMETRY_OUTPUT_FORMAT"]; !ok {
	d.cfg.Params["GEOMETRY_OUTPUT_FORMAT"] = &wkb
	}
	if _, ok := d.cfg.Params["GEOGRAPHY_OUTPUT_FORMAT"]; !ok {
	d.cfg.Params["GEOGRAPHY_OUTPUT_FORMAT"] = new("WKB")
	}
	if _, ok := d.cfg.Params["GEOMETRY_OUTPUT_FORMAT"]; !ok {
	d.cfg.Params["GEOMETRY_OUTPUT_FORMAT"] = new("WKB")
	}

[lidavidm]

Also, if a user explicitly sets this to something that is not WKB, we should avoid adding the GeoArrow type and metadata, right?

[jatorre]

That is an interesting point. Snowflake I believe is the only engine that allows you to configure how the output of geo data types are encoded.

My feeling is that if the query or table is returning a native geometry or geography type we should always encode as WKB and mark it as geoarrow. It is not that you can have gearrow encoded on different formats (well you can with WKB vs native arrow objects but that’s another thing). The goal is to preserve the type so I don’t think it makes sense to change that.

But if the user does st_astext(geom) then it becomes text and it should be retuned as that. So essentially behaving like everybody else. You use functions to specify output formats (as_text, as_wkb, as_geojson,as_gml…).

So since this is adbc I would say no.

[jatorre]

In other words. We ignore because we override whatever output format the user has specified.

[lidavidm]

We should make this opt-in. It would also be good to document it in snowflake.md, and add validation cases for geometry/geography.

[jatorre]

Yeah, I don’t know. It really feels this should be fixed upstream, and I agree this is too much… yeah affecting the entire driver for this issue is too much. Maybe this whole thing should not be fixed until snowflake fixes upstream. The workaround is tooo bad.