Where Your Data Lives

Every GeoLens dataset appears in one catalog, but its data does not always live in the same place. Some origins create a copy that GeoLens manages, one serves an existing table in place, and one keeps a live reference to a remote asset. That difference determines what must be backed up, whether the upstream system must stay available, and what refresh can do.

The five origins at a glance

Origin	Where the working data lives	What GeoLens stores	How it changes
Uploaded	Vector and tabular rows in GeoLens’s PostgreSQL/PostGIS database; raster data as a Cloud-Optimized GeoTIFF (COG) in configured object storage	A managed dataset plus source filename and fingerprint	Supply a replacement file. GeoLens cannot re-fetch a file from your computer.
Created	An editable table in GeoLens’s PostgreSQL/PostGIS database	The managed table and catalog metadata; no upstream pointer	Edit the dataset. Source refresh does not apply because there is no upstream source.
PostGIS	The registered table, inside the same PostgreSQL database GeoLens uses	A catalog record and a pointer to the existing schema and table; no duplicate table	Change the table through its normal owner or ETL process. GeoLens reads the current rows in place.
Service	A GeoLens-managed copy in PostgreSQL/PostGIS	The copied rows and a system-managed pointer to the service type, endpoint, and layer	Run a manual refresh to fetch the same layer again and replace the local copy after a successful load.
STAC	The remote asset at the stored STAC URL	Catalog metadata and a live item/asset reference; not the asset bytes	The asset stays remote. Source checks contact it, but do not turn it into a managed copy.

Two catalog entries sit outside this vocabulary. A virtual raster (VRT) is composed from other datasets rather than fetched from anywhere, so it carries no origin badge and has no upstream source to refresh — but it is not weightless: GeoLens writes the VRT document and its quicklook images to configured object storage. Rebuilding one re-reads its member datasets rather than contacting an upstream system, so back up the member datasets and object storage together. A collection is a grouping, holds no dataset row of its own, and has neither an origin nor a refresh.

The Source panel on a dataset detail page names the origin and storage mode. It also shows the safe source pointer when one exists. See Dataset Detail for the rest of the panel.

Uploaded data is a managed copy

An upload is input to an ingest job, not an archival promise. After GeoLens validates and normalizes it:

vector and tabular content is loaded into PostgreSQL/PostGIS;
raster content is converted to a COG and stored through the configured object storage backend; and
temporary upload and staging objects are cleaned up after successful ingest.

GeoLens records the source filename and, when available, a file fingerprint for provenance. It does not retain a remote location it could contact later. Keep your original file in its own records or archival system if you need the exact submitted artifact.

To update an uploaded dataset, use the replacement or re-import workflow and supply the new file. This preserves the catalog identity while replacing the managed data. A source-only refresh cannot reconstruct bytes that existed only on the uploader’s computer.

Created datasets have no upstream source

A dataset created in GeoLens is an owned, editable table in PostGIS. Features added through GeoLens, its API, or a connected GIS client change that table directly. There is no file, service, or catalog to re-fetch, so source refresh is not applicable and source freshness remains unknown.

Analysis outputs are ordinary managed datasets too: GeoLens materializes the result rather than keeping a live computation attached to the input layers.

Registered PostGIS tables stay in place

Register Table catalogs a table that already exists inside GeoLens’s own PostgreSQL database. GeoLens stores the schema-qualified table name and the catalog metadata it derives, but it does not create a second table. Feature queries, tiles, and exports read the registered table directly, so row changes made by its ETL process or another authorized client are visible on subsequent reads.

Registration is not external-database federation. The form discovers tables in the database GeoLens is already connected to; it does not accept another database host, DSN, or database credential.

There is no remote payload to re-fetch. Updating the source means updating the registered table. Any source operation that recounts features or recomputes extent and schema metadata must leave the table itself untouched.

Service imports are refreshable local snapshots

WFS, ArcGIS FeatureServer, and OGC API Features imports are one-shot local copies. During import, GeoLens fetches the selected layer and loads it into PostGIS. Maps, feature queries, and exports then read the local table; GeoLens does not proxy those requests to the remote service.

That means the existing dataset keeps working when the service is temporarily offline, but it does not become current by itself. A manual Service refresh:

reads the system-managed service and layer pointer from the dataset;
fetches the upstream layer into an attempt-specific staging table;
compares the incoming schema with the current schema; and
swaps the new table into place only after the fetch and load succeed.

The dataset ID, catalog metadata, grants, and map references stay attached to the dataset. A failed refresh leaves the last working copy serving and does not move Last refreshed forward.

An origin health check answers whether the service can be reached. It does not compare every remote feature with the local copy, so Healthy does not mean up to date.

For a protected service, provide access again when the manual refresh asks for it. GeoLens does not put that credential in the dataset’s origin pointer. Use a short-lived, least-privilege token, and never place a password or token in the source URL. Protected refresh also requires the instance’s shared credential store so the token can reach a worker without becoming part of a durable job record. That store is Valkey/Redis, addressed by REDIS_URL, which is unset in a default install — until it is set, GeoLens refuses a token-bearing refresh up front with a credential_store_unavailable error. See Configuration for the REDIS_URL setting. Public-service refresh does not need it.

STAC assets remain live references

A STAC import creates a cataloged raster dataset whose asset URL still points to the provider’s storage. GeoLens keeps the item and asset identity it needs to find the source, but it does not download the asset into managed object storage. Raster reads therefore depend on the remote object remaining reachable.

Checking a STAC source contacts the stored item and asset and records whether they are healthy, missing, or inaccessible. The check does not copy the asset, and it does not rewrite a moved item or asset pointer — that is refresh’s job, not the health probe’s.

A STAC dataset can be refreshed too, though not the same way a Service dataset is. Refresh re-reads the stored item, and if the item itself has moved as well as its asset, it searches the collection by the item’s recorded identity to relocate it before following through to the asset’s current location — updating the stored pointer either way. It never downloads the asset into managed storage; the dataset stays a live reference throughout, so there is still no local snapshot for refresh to replace. A binding recorded before GeoLens tracked item identity has nothing to verify a candidate item against, so refresh refuses it rather than guessing; re-import the item from the STAC catalog to record that identity.

A catalog behind a credential follows the protected-service rules above from 1.19.0: supply the credential again on each refresh, and set REDIS_URL so it can reach the worker. A refresh of a catalog that needed one before is refused up front when you send none. The asset itself is still read anonymously, since the tiler fetches it out of process, so an asset with its own credential reports as inaccessible rather than rendering.

If you need an independent, backup-contained copy of a referenced asset, export or download it and import that file as an Uploaded dataset. That creates a separate managed dataset; it does not change the original STAC dataset’s storage mode.

Read source state literally

Source state is deliberately narrow:

Last refreshed is the last successful committed replacement or source update, not the most recent attempt.
Last checked is the last time GeoLens contacted a remote origin, whether the check or refresh succeeded or failed.
Source freshness compares Last refreshed with the dataset’s declared update frequency. It is advisory. It does not poll the upstream system, verify that content is identical, or schedule a refresh.
Source health reports reachability for origins GeoLens can probe. It says nothing about whether the remote content changed.
Schema drift records the result of comparing schemas during a committed refresh. Unknown means no such comparison has been recorded.

Health values and detail codes

source_health holds one of four values. A probe returns only the first three; unknown is what a dataset no probe has touched reads as:

Value	What GeoLens established
`healthy`	The origin answered and the resource is there.
`missing`	The origin answered that the resource is gone.
`inaccessible`	The origin could not be read, so whether the data is still there is undetermined.
`unknown`	Never probed, or an origin with nothing to probe.

missing and inaccessible stay separate on purpose. A source that has begun demanding authentication answers much like one that was deleted, and calling that Missing would send you to replace data that is still sitting there.

When health is missing or inaccessible, source_health_detail carries one code from a fixed GeoLens vocabulary. It is null when the origin is healthy and when it has never been probed. It is never provider text, a URL, or a response body.

Detail code	What happened
`not_found`	The probed resource answered 404 or 410.
`item_withdrawn`	The STAC item document itself is gone.
`unauthorized`	401 or 403 — access was lost, and the resource may be intact behind it.
`server_error`	The origin returned a 5xx.
`unexpected_status`	Another error status, or a body GeoLens could not read.
`timeout`	The origin did not answer in time.
`network_error`	Connection, DNS, TLS, or redirect failure.
`blocked_by_policy`	GeoLens’s own network-safety check refused the target.

The dataset page turns both into a sentence; geolens status <dataset_id> prints the raw values on its Health row.

Refresh failure codes

A failed refresh run records an error_code next to a short redacted message. Both are served by GET /datasets/{id}/refresh-runs to the dataset’s owner and to admins only; the dataset page shows the message to those readers.

`error_code`	What it means
`source_missing`	The origin said the source is gone: a registered table that no longer exists, a withdrawn STAC item, a removed asset. Health becomes Missing and the catalog entry keeps its last measurement.
`source_inaccessible`	The origin could not be read — denied, a 5xx, a timeout, a lost database connection. Nothing is concluded about the data.
`credential_expired`	The credential for a protected service was already spent or had expired. Run the refresh again with a fresh token.
`credential_store_unavailable`	The token never reached the worker, because the worker could not reach the shared credential store the API could. An operator has to make `REDIS_URL` resolvable and reachable from the workers as well as the API. When the API can see the problem from its own side it refuses the request up front under this code instead, and no run is recorded.
`validation_failed`	The replacement content failed validation. The existing data keeps serving.
`superseded`	The dataset changed while the attempt was running, so the older answer was discarded rather than written over the newer state. Refresh again.
`dispatch_failed`	The run could not be queued at all.
`abandoned`	The run sat unfinished for more than an hour and no worker task for it could still be found, so it was closed as cancelled. A slow but live refresh is protected by that second condition, not by the clock.
`file_refresh_failed`, `service_refresh_failed`, `postgis_refresh_failed`, `stac_refresh_failed`, `raster_refresh_failed`	One origin path’s catch-all, used when nothing more specific applied. Read the message.

Only source_missing and source_inaccessible say anything about the origin itself. The rest describe the attempt, and leave whatever the last conclusive check recorded exactly where it was.

What to include in backups

The origin determines what a self-contained backup needs:

Data	Backup requirement
Catalog metadata, uploaded vectors, created datasets, and Service copies	Back up PostgreSQL/PostGIS.
Registered PostGIS tables	Include the registered schemas and tables in the database backup, not only catalog schemas.
Uploaded rasters and other managed raster products	Back up configured object storage as well as their catalog rows in PostgreSQL.
Live STAC assets	GeoLens backs up the pointer, not the third party’s bytes. Preserve or copy the upstream asset separately if you need to control recovery.
Original uploaded files	Keep them in your own source archive; GeoLens staging storage is not that archive.

See Backups & Restore for the operator workflow and Taking your data with you for exports and complete data-movement options.