Kai Johnson's Diary | Qloverleaf - An Overpass QL interpreter using the QLever database | OpenStreetMap

Select Language

Loading...

Close

Kai Johnson's Diary

Qloverleaf - An Overpass QL interpreter using the QLever database

Posted by Kai Johnson on 8 June 2026 in English.

I’ve been working recently on a personal project to investigate how much of the<br>Overpass query language<br>could be implemented using a different back end database, namely the<br>QLever database.

Overpass is the most widely used public interface for querying OSM data. It is<br>relatively easy to use and understand and its outputs in GeoJSON or OSM XML are<br>readily integrated into OSM or other geospatial tool chains for visualization or<br>other processing.

But Overpass is somewhat of a victim of its success. Demand for the public Overpass<br>service has recently outpaced server capacity. My earlier work on a container image<br>for Overpass was intended to help<br>scale capacity by making it easier for data consumers to run their own local Overpass<br>servers.

This project looks in a different direction. What if the Overpass QL with its ease of<br>use and its integration into other tools were available on top of a different data<br>source?

QLever

QLever is a SPARQL<br>database developed by the Chair for Algorithms and Data Structures at the University<br>of Freiburg. SPARQL is an RDF query language<br>where the data are represented as “triples” of a subject, predicate, and object.

QLever represents geospatial data as<br>WKT and<br>can perform geospatial operations on WKT. The<br>osm2rdf conversion generates WKT data for<br>every OSM element. So, the data in QLever stores the complete geometry from OSM.

But the key to QLever’s performance with OSM data is that in the conversion from<br>OSM PBF to TTL (Terse RDF Triple Language), osm2rdf<br>generates triples for every element to describe their spatial relations with other<br>elements. That is, osm2rdf pre-computes the spatial relations sfIntersects, sfContains,<br>sfCovers, sfTouches, sfCrosses, sfOverlaps, and sfEquals between all OSM elements.

QLever excels at querying RDF triples. And the precomputed spatial relations for<br>imported OSM data make many types of queries blindingly fast in QLever. Want to find all<br>the features within a closed way or relation? That answer is one lookup away in<br>QLever.

Differences

The imported RDF triples for OSM data also contain all the structural relations<br>between elements. Want to recurse down to find all the ways and nodes that are direct<br>or indirect members of a relation? Just follow the path through the triples.<br>Traversing upward to find all the parent elements that refer to a node or a way just<br>reverses that path.

That upward path to find parents is something that Overpass struggles with. Overpass<br>has the original structural relationships: a way has member nodes, a relation has<br>member relations, ways, or nodes. But it does not maintain the reverse relationships. To<br>find the parents of a node, for example, Overpass must do a full scan of elements in<br>the same spatial bin to search for references to the node.

On the other hand, QLever does not have a direct geospatial index for OSM data.<br>Finding OSM elements by spatial properties such as intersection with or containment in<br>other elements is trivial in QLever. But finding OSM elements within a bounding box or<br>other arbitrary region requires a full scan over all the elements’ geometry.

QLever also does not store the version history of OSM elements as Overpass can. This<br>notable gap is discussed in more detail below.

Overpass treats all scalar data types as strings, unless they are used in a numeric<br>context and they “look” like numbers, in which case they are treated as numbers.<br>Unlike the dynamic typing in Overpass, SPARQL has strict data typing for scalars with<br>explicit type conversions required in many instances.

In addition, the Overpass query language is imperative. Each statement specifies an<br>operation to be performed and changes the state of the result sets. In contrast,<br>SPARQL is a declarative language. Each statement describes constraints on the result<br>set. One of the challenges of this project was to explore how the one language could<br>be mapped to the other.

Grammar

The main references for the Overpass query language are the Overpass QL language<br>reference and Overpass<br>language guide on<br>the OpenStreetMap Wiki. These two references are somewhat informal and sometimes don’t<br>explain all the details of the query language or its grammar.

This project started with detailed research into Overpass QL using a local v0.7.62.11<br>Overpass server and the latest source code. The result of that research is a formal<br>W3C EBNF grammar for Overpass QL.

The research into the Overpass QL grammar also looked into the Overpass XML query<br>format and found that this is a direct transformation of the internal AST within the<br>Overpass implementation. Because of the direct relationship between the Overpass XML<br>query format and the internal Overpass implementation,...