Add documentation for spatial query features

[ullingerc]

No description provided.

[sparql-conformance]

Conformance check passed ✅

No test result changes.

Details: https://qlever.cs.uni-freiburg.de/sparql-conformance-ui?cur=a5231f3296cc305a7bb01526e8394850c5c9ff17&prev=f856919842dc3492d2236fe4822d6662b582edcc

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.99%. Comparing base (f856919) to head (a5231f3).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1581      +/-   ##
==========================================
- Coverage   89.00%   88.99%   -0.01%     
==========================================
  Files         368      368              
  Lines       33888    33888              
  Branches     3828     3828              
==========================================
- Hits        30161    30159       -2     
- Misses       2473     2474       +1     
- Partials     1254     1255       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[hannahbast]

@ullingerc Thanks a lot, this is great. I have a comment and a question:

1. I think it's better to move this kind of documentation to https://github.com/ad-freiburg/qlever/wiki and link to it (with a short explanation) from the main README.md of https://github.com/ad-freiburg/qlever. The reason is that documentation is more frequently updated (or simply corrected) than code, and we don't want a commit for every such update. For the same reason, the QLever CLI is in a separate repository https://github.com/ad-freiburg/qlever-control.

2. You mention that QLever does not yet provide ad-hoc computation of the spatial predicates contains, intersects, and so on. I wonder: since the S2 library is already integrated now, wouldn't it be fairly straightforward to use it for this?

[ullingerc]

@hannahbast Thank you very much for your feedback, A few thoughts on this:

1. Okay, I see. I totally agree that we should stick to the project's conventions. While I think that, personally, I would prefer a self-contained git repository that can for example be easily moved to a different platform, I agree that we should be consistent: I will change this as you suggested.

2. Thanks for bringing this up. I also already thought about this. S2 provides some functions, also for example to calculate the centroid ad-hoc. But it would involve quite some infrastructure code (for parsing the different types of WKT strings, converting each of them to the adequate data structure in s2, the wrapping code for each of the functions, etc.). Therefore my suggestion is to postpone this for a few weeks, while I still have lots of other work to do. If I can find time, I will be glad to implement this. I think it would be very useful to have the ad-hoc methods as a sort of fallback for the precomputed ones. For example when importing a small dataset without OpenStreetMap this would be a practical shortcut.

[hannahbast]

@ullingerc Thanks for the explanation! I have a follow-up question regarding the spatial join to understand this better:

Let's consider any one of the spatial functions, say geof:sfContains and let's consider the special case, where we use it in a FILTER and both arguments are variables and both variables are bound by parts of the remaining query. Then, instead of FILTER geof:sfContains(?x, ?y), we could equivalently write ?x <spatial-join:contains> ?y, where the latter is a magic predicate with the appropriate semantics.

That looks very similar to the magic functions <nearest-neighbors:k>, <nearest-neighbors:k:m>, and <max-distance-in-meters:m, which you have already implemented.

My question is: Would the implementation of such a magic <spatial-join:contains> predicate be analogous, or is there an additional complication?