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. |

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. When that store is unavailable, GeoLens refuses the protected refresh; 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.

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.

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.