GeoParquet through the REST API¶

This guide shows how to publish GeoParquet files as vector layers through the REST API, using the "Parquet" datastore contributed by the parquetry extension. The store is read-only and reads GeoParquet from the local filesystem, Amazon S3 (and S3-compatible services), Azure Blob Storage, Google Cloud Storage, or plain HTTP servers.

The parquetry store is independent from the DuckDB-based "GeoParquet" community store; both can run side by side, and existing stores of either type are unaffected by the other.

Prerequisites¶

• GeoServer Cloud 3.1.0 or newer. The parquetry extension is enabled by default (geoserver.extension.parquetry.enabled: true).
• GeoParquet files reachable from the GeoServer pods: a mounted volume or object storage.
• Admin credentials for the REST API.

Every command below uses these variables; set them to match your deployment:

export GEOSERVER_URL="https://geoserver.example.com/geoserver/cloud"
export REST="$GEOSERVER_URL/rest"
export AUTH="admin:geoserver"

export WORKSPACE=naturalearth
export STORE=ne

Choosing the store layout¶

The geoparquet connection parameter accepts a single file, a directory, or a glob; layer-grouping controls how a directory maps to layers:

A directory of per-theme files, one dataset per file (the Natural Earth layout: countries.parquet, coastlines.parquet, ...), wants layer-grouping=file. A partitioned dataset, many files with one schema, wants the default merged.

Publish a directory of GeoParquet files¶

The walkthrough publishes a directory of per-theme files from a volume mounted on every pod, with one layer per file.

1. Create the workspace¶

curl -sS -u "$AUTH" -X POST -H "Content-type: text/xml" \
    -d "<workspace><name>$WORKSPACE</name></workspace>" "$REST/workspaces"

Expect 201 Created.

2. Create the datastore¶

curl -sS -u "$AUTH" -X POST -H "Content-type: text/xml" -d @- \
    "$REST/workspaces/$WORKSPACE/datastores" <<EOF
<dataStore>
  <name>$STORE</name>
  <type>Parquet</type>
  <connectionParameters>
    <entry key="geoparquet">file:///data/ne/</entry>
    <entry key="layer-grouping">file</entry>
  </connectionParameters>
</dataStore>
EOF

Expect 201 Created. The path must be readable from every GeoServer pod; on Kubernetes that means a volume mounted by all vector-serving services.

3. Discover the available feature types¶

curl -sS -u "$AUTH" \
    "$REST/workspaces/$WORKSPACE/datastores/$STORE/featuretypes.json?list=available"

The response lists one feature type per .parquet file, named after the file:

{"list":{"string":["boundary_lines","coastlines","countries","disputed_areas","populated_places"]}}

4. Publish the layers¶

One POST per feature type from step 3:

curl -sS -u "$AUTH" -X POST -H "Content-type: text/xml" \
    -d "<featureType><name>countries</name></featureType>" \
    "$REST/workspaces/$WORKSPACE/datastores/$STORE/featuretypes"

Expect 201 Created. The schema, CRS, and bounds come from the GeoParquet metadata; no manual bounding box computation is needed.

5. Verify¶

Read features over WFS and render a map over WMS. On a scaled deployment these are served by wfs and wms pods, different containers than the one that handled the REST calls; a successful response is the cross-pod check:

curl -sS "$GEOSERVER_URL/$WORKSPACE/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=$WORKSPACE:countries&count=5&outputFormat=application/json"

curl -sS -o map.png \
    "$GEOSERVER_URL/$WORKSPACE/wms?service=WMS&version=1.1.1&request=GetMap&layers=$WORKSPACE:countries&bbox=-180,-90,180,90&width=1000&height=500&srs=EPSG:4326&format=image/png"

The same store over S3¶

Only the datastore creation changes: the geoparquet URI points at the bucket and the storage.* parameters configure the backend. Steps 3 to 5 are identical.

curl -sS -u "$AUTH" -X POST -H "Content-type: text/xml" -d @- \
    "$REST/workspaces/$WORKSPACE/datastores" <<EOF
<dataStore>
  <name>${STORE}-s3</name>
  <type>Parquet</type>
  <connectionParameters>
    <entry key="geoparquet">s3://my-bucket/ne/</entry>
    <entry key="layer-grouping">file</entry>
    <entry key="storage.provider">s3</entry>
    <entry key="storage.s3.region">us-east-1</entry>
    <entry key="storage.s3.use-default-credentials-provider">true</entry>
  </connectionParameters>
</dataStore>
EOF

With use-default-credentials-provider=true the pods authenticate through the AWS default credential chain: environment variables, web identity token (IRSA on EKS), the shared credentials file, or the instance profile. The store configuration holds no secrets. For a public bucket use storage.s3.anonymous=true instead; static keys through storage.s3.aws-access-key-id and storage.s3.aws-secret-access-key also work, at the cost of credentials inside the catalog.

Azure Blob Storage, Google Cloud Storage, and plain HTTP servers follow the same pattern: point geoparquet at the backend's URI form and add that backend's storage.* parameters from the reference below.

Store connection parameters¶

Storage configuration properties¶

storage.provider selects the storage backend: s3, azure, gcs, http, or file. When absent, the backend is inferred from the geoparquet URI; set it explicitly for https:// URIs, which several backends can serve, and in general to make intent explicit.

storage.caching.enabled (default true) caches byte ranges in memory, cutting repeated reads against remote storage. It has no effect for local files.

S3¶

URI forms: s3://bucket/path/, or an https:// URL of the service.

Azure Blob Storage¶

URI forms: az://account/container/path, https://<account>.blob.core.windows.net/container/path, abfs(s)://.

Google Cloud Storage¶

URI form: https://storage.googleapis.com/bucket/path.

HTTP¶

URI form: any http(s):// server that supports range requests.

Local files¶

URI form: file:///path/.

Notes¶

• The store is read-only: layers serve WMS and WFS reads, and WFS transactions are rejected.
• The parquetry engine also provides Stac-GeoParquet and Apache Iceberg datastores, which are not yet production ready and ship disabled. They stay unavailable while the parquetry.geotools.stac-geoparquet.disabled and parquetry.geotools.iceberg.disabled system properties hold true; GeoServer Cloud sets both at startup unless the property is already set, and launching the services with an explicit -Dparquetry.geotools.iceberg.disabled=false (or the stac-geoparquet equivalent) re-enables the corresponding store.