Execution model

What the platform does between reading a query and painting a tile — when each callback runs, what waits for what, and which code crosses into the calculation worker.

Mappia reference, section “Writing a query”. Page: https://mappia.earth/reference/execution-model/ Generated API entries: LayersFunctions.beforeCalc, LayersFunctions.expression, LayersFunctions.afterCalc, LayersFunctions.onInputsReady, LayersFunctions.legendColor, LayerInternal.getInputs, LayerInternal.setCalculateLegend, LayerInternal.generateNewLegend, LayerInternal.pauseAndStopCalculations, LayersProperties.priority, RawMaps.operations, QueryState (https://mappia.earth/assets/api.json)

A query is read once; the map it describes then keeps working for as long as the page is open. Knowing the order of what happens — and, above all, which code runs on the page and which runs in a worker — is what makes the difference between a query that behaves and one that intermittently shows nothing.

1. From text to layers

query text
   │  evaluated as one expression, value = array of definitions
   ▼
interpretation ── groups flattened into an ordered list of layers
   │              group defaults applied, group path remembered per layer
   ▼
one layer object per definition, by kind:
   ├─ catalogue map (WMS tiles, drawn as they arrive)
   ├─ calculated map (several maps + your expression, see §2)
   ├─ vector/file layer (GeoJSON, CSV, uploaded file)
   └─ tile service (XYZ / OSM basemap)
   │
   ▼
layer panel, map, widgets declared in descriptionHtml

Interpretation is where a nested query becomes flat: a group (viewTitle with elements) contributes its own properties to each layer inside it and records the path that the layer panel shows. Within a group, entries keep the order you wrote them in, unless a priority reorders them (higher first).

Nothing has been drawn yet at this point, and no calculation has run.

2. The cycle of a calculated map

A calculated layer (source: "calculate") names several maps at once and produces a new map from their pixels. Its cycle is the part of the platform most queries interact with:

        widgets in descriptionHtml are created
                      │
                      ▼
        every input has a value ──────────► onInputsReady(inputs)
                      │
                      ▼
               beforeCalc(inputs)            ← on the page: map, DOM, other layers
                      │
                      ▼
      tiles of each named map are fetched and decoded
                      │
                      ▼
   for every pixel:  expression(layersVals, inputs)   ← in a worker
                      │
                      ▼
      legend: legendColor(value) per distinct value,
              or the entries you set with setCalculateLegend
                      │
                      ▼
                afterCalc(...)               ← on the page again
                      │
                      ▼
                   painted

Callback	Runs	Receives	Typical use
`onInputsReady`	Once every input of the layer has a value — including for layers that are not visible	`inputs`	Kick off work that needs the widgets, e.g. a first `generateNewLegend()`
`beforeCalc`	Before each calculation round	`inputs`	Read widgets, swap the maps being read (`changeLayers`), set the legend, cancel the round
`expression`	Once per pixel, in the worker	`layersVals`, `inputs`, `this` = the calculation object	The arithmetic itself
`legendColor`	Once per distinct value produced	the value	Colour scale
`afterCalc`	When the round finished - only for a layer with an `expression`: without one nothing is computed and `afterCalc` never runs	the results	Totals, notifying the parent page, enabling UI

inputs is the collected value of every widget declared in that layer’s descriptionHtml, in declaration order, and can also be read on demand with getInputs().

3. What crosses into the worker

expression is the only part of a query that does not run on the page. It is turned into text with toString() and rebuilt inside a WebWorker, together with the pixel values and the plain widget values.

Crosses into the worker	Stays on the page
The source text of `expression`	Any variable it closed over — it becomes `undefined`
`layersVals`: one value per named map, in `name` order	`window`, the DOM, the map, the platform objects
`inputs`: the widget values as a plain array, in markup order	The name map `inputs.id` (JSON keeps only an array’s elements), and widget values that are not plain data (a function, a table object, a manager’s methods)
`this`: the calculation object (`isNumeric`, `getValueFromLegend`, `nullValue`)	Your own helpers and globals

The practical rule: anything an expression needs that is not a pixel value must be computed in beforeCalc and handed over as an input — and read by position, inputs[0], inputs[1], never as inputs.id[ID], which only exists on the page. A widget whose value is an object (a loaded CSV table, a picked point) is readable in beforeCalc, not inside expression; an `` arrives as its plain global values (inputs[0].global.key).

4. What triggers a new round

A calculated layer recalculates when:

a widget that is registered as an input reports its change event — a slider moved, a text field was typed in, a CSV finished downloading, a timeline stepped;
code calls forceRecalc() on an input manager, or generateNewLegend() on the layer;
the maps being read change (changeLayers, setLayerOperation, setInsideLayerVisibility);
the layer becomes visible again, or the map moves to tiles that have not been computed.

Rounds are cancellable: pauseAndStopCalculations() stops the current one and suppresses new ones until resumeCalculations() is called once per pause. Queries that load an external resource before they can compute use this pair, so the user does not see a legend computed from half the data.

5. Waiting, and why a query must not assume

Several things load independently: the layer catalogue, each layer’s own resources, the widgets’ files (a CSV, a JSON), the legend of a stored map. The platform keeps count of what is outstanding and holds the calculation until the count reaches zero, which is why onInputsReady exists and why beforeCalc may legitimately run later than you expect.

Two consequences for a query author:

Do not read another layer’s data during interpretation. At that moment the other layer may not exist yet. Read it in onInputsReady, in beforeCalc, or in a callback.
A resource your own code fetches must be announced, otherwise the platform may calculate without it. Widgets that download something (,) do this for you; a hand-written fetch in a callback does not.

6. Tiles, zoom and decoded values

Catalogue and calculated maps are tiled. Two behaviours surprise query authors:

Beyond a layer’s maximum zoom, the platform keeps requesting the deepest tile it has and stretches it, instead of requesting a zoom the server does not publish.
The values a calculated layer reads are decoded, and how they are decoded is chosen per map with operation: the original cell value of the most central cell, the packed colour, an area-weighted sum or average, a maximum, a summed-area integral. The tokens are listed with the layer vocabulary in the layer and group model; the decoding requires the map to be published with that operation available.

When the same map appears more than once in name with different operations, each position in layersVals corresponds to one entry of the name list — the list is the contract between the query and the expression.

7. Re-applying a query

Applying a query again — from the editor, or from a parent document — re-evaluates the text from scratch: globals are re-registered, layers are rebuilt, widgets are recreated. It does not preserve anything the previous evaluation left in a page variable. This is the reason shared state belongs in the query’s globals, described in the query language.

8. Reading the console

The platform narrates this pipeline. The messages worth recognising:

Message	Means
A layer is skipped with “source not found by name”	The layer’s server was not registered before the array
“Operation X is not defined for layer Y”	The map is not published with the decoding the query asked for
“Global variable can’t be redefined”	A query global collides with a page global
A calculation that never finishes	Something is still counted as loading — usually a resource fetched without announcing it (§5)