Skip to content
Sync Server

How Sync Server works

Sync Server runs one loop: pull from a data source on a schedule, transform it into GeoJSON, cache it, and serve it as a feature service. The terms below are used throughout the rest of the documentation.

Terminology

Section titled “Terminology”
Term What it is
Base A data source with credentials — one Airtable base, one NocoDB project, one Postgres database, one HTTP endpoint. Addressed by its baseId (appXXXXXXXX for Airtable, a slug you choose for the rest).
Table One dataset inside a base. Becomes one layer in the feature service, one .geojson file, one vector-tile layer.
Provider The adapter that talks to the upstream system. Chosen per base (and overridable per table).
Strategy What happens to a table’s data once it’s fetched — cache it, publish it to ArcGIS, join it, and so on.
Cache The GeoJSON that every read endpoint is served from. Nothing you read comes live from the provider.

The sync loop

Section titled “The sync loop”
a scheduled sync runs for a base
             │
   fetch from the source  ← Airtable / NocoDB / SQL / HTTP
             │
   for each table: run its strategy
             │
        the cached GeoJSON
             │
   FeatureServer · GeoJSON · vector tiles · records API · exports · MCP  ◀── all read from here

Reads never block on a sync, and a sync never blocks a read: the cache is only swapped once a fetch succeeds.

Providers

Section titled “Providers”
Provider Source Writable Notes
airtable Airtable base ✅ Real-time webhooks, attachments (read + write)
nocodb NocoDB project ✅ Webhooks, attachments (read only)
postgres PostgreSQL tables/views ✅ Transactional writes, so table-wide rollback works
postgis PostgreSQL + PostGIS ✅ Native geometry; vector tiles served per-tile with ST_AsMVT
mssql MS SQL Server ✅ Schema introspection
fetch Any HTTP endpoint returning GeoJSON or CSV ❌ Read-only mirror
tsip TSIP ❌ Purpose-built adapter

“Writable” decides whether the records API, applyEdits, the grid and the MCP write tools do anything — read-only providers reject edits rather than silently dropping them.

Strategies

Section titled “Strategies”

A strategy is set per table, and they’re mutually exclusive.

Strategy What it does
cache Cache the GeoJSON. The default, and what every read endpoint needs.
publish Diff the data against a hosted ArcGIS Online / Portal feature service and apply the adds, updates and deletes.
upload Bulk-replace an ArcGIS feature service rather than diffing it.
data-pipeline Transform on the way through — CSV cleanup, field mapping, geometry derivation.
join Merge several sources into one table on a join field.
layer Create and manage a layer within a multi-layer service.

Freshness

Section titled “Freshness”

cacheHours sets how stale a table may get before a scheduled sync refreshes it; it can be set globally, per base, or per table. Three things can refresh a table sooner:

  • A manual sync — POST /api/v0/bases/{baseId}/sync (rate-limited to 4 per hour per base).
  • A webhook — Airtable and NocoDB push changes in as they happen.
  • An edit — a write through Sync Server updates the cache in place, so it never shows a stale value for a change it made itself.

Next

Section titled “Next”