Skip to content

Configuration Reference

Portolan reads catalog settings from .portolan/config.yaml.

Vector Conversion

The conversion.vector block controls how Portolan writes GeoParquet.

Setting Values Default Meaning
spatial_index a5 | h3 | kdtree | none | quadkey | s2 none Spatial index column to add.
resolution auto | integer auto Index resolution. auto uses the geoparquet-io defaults.
sort hilbert | none | quadkey hilbert Row ordering method.
add_bbox true | false true Add a bbox covering column.
partition true | false false Produce hive-partitioned output. Requires a spatial index. 
conversion:
  vector:
    sort: hilbert
    add_bbox: true

Conforming Output by Default

sort and add_bbox carry the values the Portolan GeoParquet profile requires. rashid reads both PTL-DAT-006 and PTL-DAT-007 through the bbox covering column, so a file without that column fails portolan check. Set sort: none or add_bbox: false to turn either off.

These settings apply to portolan add and portolan convert. portolan extract arcgis always writes the covering column and does not read this block.

add also rewrites a GeoParquet you hand it when that file carries no covering column. A file that already has one is copied untouched, so a large conformant file costs nothing. --force applies the same test.

The rewrite is a full read, sort, and write, not a copy. add reports the file size before it starts, and it needs free space for a second copy of the file while it runs. Above 1GB add also prints a warning, because the read and the sort take long enough to look like a stall. Every schema metadata key the file carried is restored afterwards, pandas and publisher keys included.

The Rewrite Never Loses Data

add compares the rewritten file against the source before it swaps them in. It checks the row count, the column set, and the declared CRS. It keeps your file and prints the reason when any of those would be lost. The file then stays non-conformant, and check reports it. A projected GeoParquet keeps its CRS through the rewrite:

$ portolan add roads/data.parquet
→ Rewriting data.parquet (11.1KB): it carries no bbox covering column
✓ Added 1 file to 1 collection

add does not inspect row order. To reorder a file that has the column but is not sorted, run portolan add <path> --force --reconvert. That is also the way to apply sort to an existing file when you set add_bbox: false, because the footer then shows nothing add can act on.