Parqtiles

Parqtiles is a declarative, plan-driven CLI for converting GeoParquet datasets into PMTiles, designed for reproducible and cloud-native vector tile workflows.

Concepts

• Declarative plans
  You describe what tiles should look like — Parqtiles handles the execution.

• Schema-first transformation
  Tile properties are defined explicitly as a schema, forming a stable contract for downstream consumers.

• Reproducible artifacts
  The same plan and inputs always produce the same tiles.

• Local-first, cloud-ready
  Run locally with Docker, or scale out with ECS or CI pipelines.

Plan format

Plans are the source of truth and define intent, not procedures.

Top-level sections:

• version
• source
• transform
• tiling
• output
• runtime

The plan file must be explicit and deterministic. Hidden defaults are avoided, except source.geometry_column which defaults to geom if omitted.

Quick start (local Docker)

Directory structure

Parqtiles-demo/
├─ parqtiles.plan.yaml
├─ data/
│   ├─ buildings_000.parquet
│   └─ buildings_001.parquet
├─ out/
└─ .tmp/

Plan file

version: 0.1

source:
  format: geoparquet
  uri: /work/data/*.parquet
  geometry_column: geom

transform:
  where: "building_type IS NOT NULL"

  schema:
    height:
      from: building_height
    kind:
      from: building_type

# Optional: explicit input column list for projection
# select:
#   - geom
#   - building_height
#   - building_type

tiling:
  layer: buildings
  minzoom: 6
  maxzoom: 14
  drop_densest_as_needed: true
  extend_zooms_if_still_dropping: true

output:
  format: pmtiles
  uri: /work/out/buildings.pmtiles

runtime:
  tmpdir: /work/.tmp

Build tiles

If parqtiles.plan.yaml exists in the working directory, Parqtiles will automatically load it.

mkdir -p out .tmp

docker run --rm \
  -v "$PWD:/work" \
  parqtiles:latest \
  parqtiles build

The generated PMTiles file will be written to:

out/buildings.pmtiles

Validate a plan

parqtiles validate

This checks:

• plan structure
• schema consistency
• zoom constraints
• obvious configuration errors

Inspect input data

parqtiles inspect --input "/work/data/*.parquet"