---
type: Domain Concept
title: Map connection
description: A saved provider-neutral data selection attached to one map.
tags: [map, connection, query, pushdown]
visibility: public
---

# Meaning

A Map Connection answers **which data from one Provider is attached to a
Map**. It is distinct from the [Layer](/presentation/layer.md), which answers
how that selected data is presented.

One Add data action creates one immutable connection identity. A connection may
produce one Layer or a contiguous group of Layers, depending on Channel
composition. All those Layers share the same connection query.

# Owns

- The exact Provider and selected Channel subset.
- A bounded, versioned, provider-neutral query keyed by the Channel's immutable
  `export_key`.
- Saved temporal ranges, one supported comparison mode, and future acquisition
  predicates that change which data belongs to the map.

The current viewer cursor is device-local and does not rewrite the connection.
Colors, opacity, labels, and visualization mode remain Layer presentation.

# Execution

The renderer or acquisition planner translates normalized connection query
terms into provider requests only when a Channel declares that capability.
Unsupported terms remain residual GeoLama filtering; provider-specific
parameter names are never persisted in the connection query.

The query builder is capability-neutral: each supported query family
normalizes only its own Channel clause. Annual raster periods are the first
implementation; spatial bounds, categories, and other temporal windows must
use the same versioned clause boundary rather than adding Provider fields to a
Layer or to the root connection object.

For raster periods the semantic `period_id` is pushed directly into the tile
request and authorized against both Channel capability and the saved Map
Connection range/mode. This avoids fetching an unrestricted raster and then
pretending it was filtered in presentation.

# Portability and access

Map Connections are RLS-protected through their Map. Copy and versioned map
recipes preserve the normalized query. Recipe identities use Channel
`export_key`, not environment-local UUIDs.

Layer settings save Layer presentation and the shared Map Connection query in
one database transaction. A validation or authorization failure rolls back
both objects, so the UI cannot display a saved style with stale data selection.