gpkgio

type Feature struct {
	Attributes map[string]any
	Geometry   geometry.Geometry
}

type FeatureTable struct {
	Name     string
	GeomCol  string
	SRID     int32
	GeomType string
}

type GeoPackage struct {
	// contains filtered or unexported fields
}

type ReadOptions struct {
	// Layer names the feature table to read. Required when the file
	// has more than one feature table; optional otherwise.
	Layer string

	// Columns optionally restricts the read to these column names.
	// nil / empty means "read every column". The geometry column
	// is always included when it's present in the source layer,
	// even if it isn't listed here — GeoPackage's whole point is
	// geometry, and dropping it silently would surprise users. If
	// you truly want an attribute-only projection, use
	// `SELECT *` directly against the underlying sql.DB.
	Columns []string

	// Where is an optional SQL WHERE fragment appended verbatim
	// after WHERE in the SELECT. Callers are responsible for their
	// own quoting — this is a lower-level knob than a full
	// gobi.Expr predicate. ScanFile lifts predicate pushdown into
	// this automatically for expressions the SQL translator can
	// handle; ReadFile leaves it to callers.
	//
	// Use `?` placeholders in the fragment and supply matching
	// values via WhereArgs — driver-safe parameterization. Callers
	// concatenating literal values into the string are responsible
	// for their own escaping.
	Where string

	// WhereArgs holds the positional bind arguments for `?` markers
	// in Where. Filled automatically when ScanFile pushes a
	// translated predicate down; callers who set Where by hand can
	// supply their own args here.
	WhereArgs []any

	// Limit caps the number of rows returned. 0 = unlimited.
	Limit int64

	// Allocator overrides the arrow allocator used for the produced
	// Frame's columns. nil = memory.DefaultAllocator. Provided for
	// callers who pool arrow buffers across pipelines.
	Allocator memory.Allocator
	// contains filtered or unexported fields
}

type WriteOptions struct {
	// Layer names the feature table to create/replace. Required.
	// Must be a valid SQLite identifier (letters, digits, underscore,
	// not starting with a digit) — WriteFile will reject anything
	// else so we can safely interpolate it into DDL without a full
	// quoting round-trip.
	Layer string

	// GeomCol names the geometry column in the output layer.
	// Defaults to the first Frame column tagged as WKB geometry
	// (via gobi.GeometryField). If the Frame has no geometry
	// column at all, the file is written as an attribute-only
	// table (still valid GeoPackage, just no gpkg_geometry_columns
	// entry for this layer).
	GeomCol string

	// SRID is the spatial reference identifier stamped into every
	// row's GPB header + registered in gpkg_contents. Defaults to
	// the value carried by the geometry column's schema metadata
	// (gobi.MetaGeometryCRS); if that's unset, defaults to 4326.
	//
	// The corresponding row in gpkg_spatial_ref_sys is inserted
	// on-demand — the default 4326 (WGS84) is always registered
	// even for attribute-only layers so the file passes strict
	// validators.
	SRID int32

	// BatchSize is the number of rows per transaction commit. Higher
	// values reduce commit overhead but grow the WAL / journal on
	// crash-safety trade-off. 1000 is a reasonable default matching
	// GDAL's ogr2ogr for GPKG output.
	BatchSize int

	// SkipRTree, when true, disables creation of the standard
	// GeoPackage rtree_<layer>_<geomcol> shadow table. Skipped
	// automatically when the Frame has no geometry column.
	//
	// The RTree is created by default because the per-insert
	// overhead is small and it unlocks fast bbox filtering on
	// downstream reads (both from gobi and from external tools
	// like QGIS / GDAL). Use this opt-out only when you're
	// writing intermediate scratch files where read-side
	// filtering doesn't matter.
	SkipRTree bool

	// Replace, when true, drops any pre-existing layer with the
	// same name (feature table + gpkg_contents row + gpkg_geometry_columns
	// row + RTree shadow tables + triggers) before creating the new
	// one. When false, WriteFile errors if the layer already exists —
	// the safer default that keeps us from silently clobbering data
	// in an existing multi-layer GeoPackage.
	Replace bool
}