From 9702f7502f3afd6c3e2f95161e9fecf8d1369fe3 Mon Sep 17 00:00:00 2001 From: ullingerc Date: Thu, 24 Oct 2024 13:56:18 +0200 Subject: [PATCH 1/2] Add documentation for spatial query features --- docs/spatial_queries.md | 80 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/spatial_queries.md diff --git a/docs/spatial_queries.md b/docs/spatial_queries.md new file mode 100644 index 000000000..6611f45b8 --- /dev/null +++ b/docs/spatial_queries.md @@ -0,0 +1,80 @@ +# Spatial Queries in QLever + +QLever has limited support for features from the [OGC GeoSPARQL standard](https://docs.ogc.org/is/22-047r1/22-047r1.html). Additionally, QLever supports some custom spatial querying features. + +## GeoSPARQL geometric relations + +QLever itself currently does not support ad-hoc calculation of geometric relations (e.g. `geof:sfContains`, `geof:sfIntersects`, ...). + +However, for OpenStreetMap data, geometric relations can be precomputed as part of the dataset (e.g. `ogc:sfContains`, `ogc:sfIntersects`, ... triples) using [`osm2rdf`](https://github.com/ad-freiburg/osm2rdf). After precomputation, geometric queries are much faster than ad-hoc methods. + +Geometries from `osm2rdf` are represented as `geo:wktLiteral`, which can be addressed by `geo:hasGeometry/geo:asWKT`. `osm2rdf` also provides centroids of objects via `geo:hasCentroid/geo:asWKT`. Please note that the geometric relations are given as triples between the OpenStreetMap entities, not the geometries. + +### Example: All buildings in the city of Freiburg + +```sparql +PREFIX geo: +PREFIX osmkey: +PREFIX ogc: +PREFIX osmrel: + +SELECT ?osm_id ?hasgeometry WHERE { + osmrel:62768 ogc:sfContains ?osm_id . + ?osm_id geo:hasGeometry/geo:asWKT ?hasgeometry . + ?osm_id osmkey:building [] . +} +``` + +Try it: + +## GeoSPARQL functions + +Currently QLever implements these functions from GeoSPARQL: + +### `geof:distance` + +The function `geof:distance(?x, ?y)` currently expects two values with `geo:wktLiteral` datatype, each containing points. It returns the distance in kilometers. Currently, non-point geometries and different units of measurement are unsupported. + +### `geof:latitude`, `geof:longitude` + +The functions `geof:latitude(?x)` and `geof:longitude(?x)` extract the latitude or longitude coordinate from a valid coordinate point with `geo:wktLiteral` datatype. + +## Nearest neighbors search + +QLever supports a custom fast spatial search operation. It can be invoked using two special predicates. + +### `` or `` + +A spatial search for nearest neighbors can be realized using `?left ?right`. The variables `?left` and `?right` must refer to points with `geo:wktLiteral` datatype. Additionaly, please replace `k` and `m` with integers as follows: + +- For each point `?left` QLever will output the `k` nearest points from `?right`. Of course, the sets `?left` and `?right` can each be limited using further statements. +- Using the optional integer value `m` a maximum distance in meters can be given that restricts the search radius. + +### `` + +The predicate `` behaves almost like the `` predicate. The parameter `m` also refers to the maximum search radius in meters. The only difference is that any number of result points within the search radius are emitted as output. + +### Example: Railway stations and supermarkets + +This example query calculates the three closest supermarkets to every railway station. QLever can answer this hard query for the entire planet's OpenStreetMap data within 8 - 10 seconds on a good consumer PC. + +```sparql +PREFIX geo: +PREFIX osmkey: +PREFIX ogc: +PREFIX osmrel: +SELECT * WHERE { + { + ?station osmkey:railway "station" . + ?station osmkey:name ?name . + ?station geo:hasCentroid/geo:asWKT ?station_geometry . + } + ?station_geometry ?supermarket_geometry . + { + ?supermarket osmkey:shop "supermarket" . + ?supermarket geo:hasCentroid/geo:asWKT ?supermarket_geometry . + } +} +``` + +Try it: From a5231f3296cc305a7bb01526e8394850c5c9ff17 Mon Sep 17 00:00:00 2001 From: ullingerc Date: Thu, 24 Oct 2024 14:00:02 +0200 Subject: [PATCH 2/2] typo --- docs/spatial_queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spatial_queries.md b/docs/spatial_queries.md index 6611f45b8..f53e65796 100644 --- a/docs/spatial_queries.md +++ b/docs/spatial_queries.md @@ -45,7 +45,7 @@ QLever supports a custom fast spatial search operation. It can be invoked using ### `` or `` -A spatial search for nearest neighbors can be realized using `?left ?right`. The variables `?left` and `?right` must refer to points with `geo:wktLiteral` datatype. Additionaly, please replace `k` and `m` with integers as follows: +A spatial search for nearest neighbors can be realized using `?left ?right`. The variables `?left` and `?right` must refer to points with `geo:wktLiteral` datatype. Additionally, please replace `k` and `m` with integers as follows: - For each point `?left` QLever will output the `k` nearest points from `?right`. Of course, the sets `?left` and `?right` can each be limited using further statements. - Using the optional integer value `m` a maximum distance in meters can be given that restricts the search radius.