# GeoLibre File Format Support and DuckDB‑WASM Spatial Conversion: A Complete Guide

> Discover GeoLibre's extensive vector format support including GeoJSON GeoParquet and more. Learn how DuckDB-WASM Spatial converts these files using ST_Read and GDAL.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-03

---

**GeoLibre imports vector formats including GeoJSON, GeoParquet, FlatGeobuf, zipped Shapefile, GeoPackage, KML/KMZ, and GML, using DuckDB‑WASM Spatial's `ST_Read` function and GDAL‑backed drivers for conversion.**

GeoLibre is an open‑source geospatial data viewer built on top of MapLibre GL‑JS and DuckDB‑WASM Spatial. Understanding which file formats GeoLibre can import and how DuckDB‑WASM Spatial handles their conversion is essential for working with diverse spatial datasets directly in the browser. This article examines the supported formats and the conversion pipeline implemented in the `opengeos/GeoLibre` codebase.

## Supported Vector File Formats in GeoLibre

GeoLibre's **Add Data** interface supports the following vector formats, as documented in [`docs/user-guide/adding-data.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/user-guide/adding-data.md):

| Format | Handling Strategy |
|--------|-------------------|
| **GeoJSON** | Direct parsing or DuckDB‑WAMS Spatial fallback |
| **GeoParquet** | Native DuckDB Parquet reader with Spatial extension |
| **FlatGeobuf** | Streaming parser with spatial index support |
| **Zipped Shapefile** (`*.zip`) | Primary: `shpjs` parser; fallback to `ST_Read` |
| **GeoPackage** (`*.gpkg`) | DuckDB‑WASM Spatial `ST_Read` with GDAL driver |
| **KML / KMZ** | Custom KML parser for styles; geometry‑only fallback to `ST_Read` |
| **GML** | DuckDB‑WASM Spatial `ST_Read` with GDAL driver |
| **Other GDAL‑supported formats** | Generic `ST_Read` path for any compiled GDAL driver |

Raster formats including **Cloud‑Optimized GeoTIFF (COG)** and standard **GeoTIFF** are supported via `maplibre-gl-raster`, though this article focuses on vector import mechanics.

## How DuckDB‑WASM Spatial Converts Imported Files

The conversion pipeline centers on **DuckDB‑WASM Spatial**, a WebAssembly‑compiled extension that brings GDAL‑powered spatial operations to the browser. In [`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md), the architecture is described as using DuckDB‑WASM for "formats that need conversion before MapLibre can render them."

### GeoParquet: Native Parquet Reader

GeoParquet files bypass GDAL entirely. The system loads the Spatial extension first, then executes DuckDB's native **Parquet reader**:

```sql
SELECT * FROM read_parquet('path/to/file.parquet')

```

This approach delivers fast, column‑wise access optimized for cloud‑native workflows. The Spatial extension automatically recognizes geometry columns encoded in the GeoParquet specification.

### GDAL‑Backed Formats: The `ST_Read` Function

For formats requiring GDAL drivers, GeoLibre constructs SQL queries using DuckDB‑WASM Spatial's **`ST_Read`** function. The core pattern appears throughout the codebase:

```sql
SELECT * FROM ST_Read('path/to/file', keep_wkb=true, layer='layerName')

```

Key parameters include:

- **`keep_wkb=true`** — Preserves Well‑Known Binary geometry encoding for efficient downstream processing
- **`layer='...'`** — Selects specific layers from multi‑layer sources like GeoPackage or FileGDB

The `ST_Read` function is implemented in DuckDB‑WASM Spatial's GDAL integration, compiled to WebAssembly. This enables browser‑based access to drivers that would traditionally require a full GDAL installation.

### Zipped Shapefile: Dual‑Strategy Parsing

Zipped Shapefiles receive special handling due to their ubiquity and complexity. As noted in [`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md):

1. **Primary path**: The **`shpjs`** JavaScript library parses the ZIP archive client‑side, extracting `.shp`, `.dbf`, and `.prj` components
2. **Fallback path**: If `shpjs` encounters malformed files or missing components, GeoLibre automatically retries with `ST_Read`, leveraging GDAL's more robust Shapefile driver

```typescript
// Conceptual flow from duckdb-vector-loader.ts
async function loadShapefile(fileBlob: Blob) {
  try {
    // Attempt pure-JavaScript parsing
    const geojson = await shpjs.readZip(fileBlob);
    return geojson;
  } catch (parseError) {
    // Fallback to DuckDB-WASM Spatial
    const sql = `SELECT * FROM ST_Read('${filePath}', keep_wkb=true)`;
    return await duckDb.query(sql);
  }
}

```

### KML/KMZ: Preserving Styles with Custom Parser

KML files present unique challenges because they contain **SimpleStyle** properties (fill colors, stroke widths, icons) that standard GDAL readers may discard. GeoLibre employs a **custom KML parser** to preserve these styling attributes. When styling information is absent or the parser encounters unsupported constructs, the system falls back to `ST_READ` for geometry extraction.

This dual approach ensures that Google Earth‑exported datasets retain their visual appearance while maintaining robust import capabilities.

### Metadata Extraction with `ST_Read_Meta`

Before loading features, GeoLibre queries **layer metadata** to determine coordinate reference systems and available layers:

```sql
SELECT * FROM ST_Read_Meta('path/to/file')

```

The metadata query enables:
- **Automatic CRS detection** and reprojection to EPSG:4326 for MapLibre compatibility
- **Layer selection UI** for multi‑layer sources
- **Schema inspection** for attribute type inference

If metadata cannot be materialized—common with older file schemas—the import proceeds with WGS84 as a safe default.

## Implementation in Source Files

### [`apps/geolibre-desktop/src/lib/duckdb-vector-loader.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/duckdb-vector-loader.ts)

This module implements the central loading logic, constructing `ST_Read` queries and managing the parser fallback chain. It handles:

- File extension detection and route selection
- SQL query generation with proper escaping (see [`packages/processing/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/types.ts) for safe quoting guidelines)
- Result transformation to GeoJSON for MapLibre consumption

### [`packages/processing/src/topology-tools.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/topology-tools.ts)

Downstream processing demonstrates `ST_Read` usage in topology operations, confirming the conversion pipeline's output is compatible with advanced spatial analysis.

## Performance and Security Considerations

The DuckDB‑WASM approach provides **near‑native performance** for format conversion while maintaining browser sandbox security. Key characteristics:

- **WebAssembly isolation** — GDAL operations run in a memory‑safe VM
- **Streaming reads** — Large files are processed without full memory loading
- **SQL injection prevention** — File paths are parameterized; see [`packages/processing/src/types.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/types.ts) for secure construction patterns

## Summary

- GeoLibre imports **eight major vector format categories**, from simple GeoJSON to complex multi‑layer GeoPackages
- **DuckDB‑WASM Spatial** serves as the universal conversion engine, exposing GDAL capabilities through the `ST_Read` SQL function
- **Format‑specific optimizations** include native Parquet reading, `shpjs` Shapefile parsing, and custom KML style preservation
- **Automatic fallback chains** ensure robust imports even with malformed or edge‑case files
- The architecture in [`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md) and implementation in [`duckdb-vector-loader.ts`](https://github.com/opengeos/GeoLibre/blob/main/duckdb-vector-loader.ts) demonstrate production‑ready patterns for browser‑based geospatial workflows

## Frequently Asked Questions

### What is the fastest format to import in GeoLibre?

**GeoParquet** offers the best performance due to its native DuckDB Parquet reader pathway, which avoids GDAL overhead and enables column‑pruned, predicate‑pushdown queries directly in the browser.

### Why does GeoLibre use both `shpjs` and `ST_Read` for Shapefiles?

The **`shpjs`** parser provides faster client‑side parsing for well‑formed files, while **`ST_Read`** offers superior robustness for corrupted or complex Shapefiles. This dual strategy maximizes success rates without sacrificing speed for typical cases.

### Can GeoLibre import data from URLs directly?

Yes. The [`duckdb-vector-loader.ts`](https://github.com/opengeos/GeoLibre/blob/main/duckdb-vector-loader.ts) implementation supports HTTP‑accessible files. URLs are passed to `ST_Read` or specialized fetchers, enabling direct import from cloud storage or geospatial data APIs without local file handling.

### Is KML styling preserved when imported into GeoLibre?

**Yes**, but only through the **custom KML parser**. If this parser fails and the system falls back to `ST_Read`, geometry will import but **SimpleStyle properties** (colors, stroke widths) may be lost. For best results, ensure KML files follow Google Earth's standard styling conventions.