This is an automated email from the ASF dual-hosted git repository.
andy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/jena-site.git
The following commit(s) were added to refs/heads/main by this push:
new f546a3b9b Updates for the Fuseki GeoSPARQL module and the spatial
indexer.
f546a3b9b is described below
commit f546a3b9bdc24aff4325d56385f6a157b2a0f51d
Author: Claus Stadler <[email protected]>
AuthorDate: Sat Jun 7 21:14:32 2025 +0200
Updates for the Fuseki GeoSPARQL module and the spatial indexer.
---
source/documentation/fuseki2/__index.md | 2 +
source/documentation/geosparql/__index.md | 14 +--
.../geosparql/fuseki-mod-geosparql.md | 117 +++++++++++++++++++++
.../documentation/geosparql/geosparql-assembler.md | 13 ++-
4 files changed, 137 insertions(+), 9 deletions(-)
diff --git a/source/documentation/fuseki2/__index.md
b/source/documentation/fuseki2/__index.md
index 9940593ad..632ff1552 100644
--- a/source/documentation/fuseki2/__index.md
+++ b/source/documentation/fuseki2/__index.md
@@ -39,6 +39,8 @@ transactional, persistent storage layer. Fuseki also
incorporates
- Client access
- [Use from Java](../rdfconnection)
- Extending Fuseki with [Fuseki Modules](fuseki-modules.html)
+- Included Fuseki Modules
+ - [GeoSPARQL Fuseki Module](../geosparql/fuseki-mod-geosparql.html)
- [Links to Standards](rdf-sparql-standards.html)
The Jena users mailing is the place to get help with Fuseki.
diff --git a/source/documentation/geosparql/__index.md
b/source/documentation/geosparql/__index.md
index 7c1980320..af46c7599 100644
--- a/source/documentation/geosparql/__index.md
+++ b/source/documentation/geosparql/__index.md
@@ -3,12 +3,14 @@ title: Apache Jena GeoSPARQL
slug: index
---
-An implementation of GeoSPARQL 1.0 standard for SPARQL query or API.
-
-Integration with Fuseki is provided either by using the
-[GeoSPARQL assembler](geosparql-assembler.html) or using the self-contained
original
-[jena-fuseki-geosparql](geosparql-fuseki.html). In either case, this page
-describes the GeoSPARQL supported features.
+An implementation of the GeoSPARQL 1.0 standard for SPARQL queries and APIs.
+
+The recommended way to integrate GeoSPARQL with Fuseki is using
+the [GeoSPARQL assembler](geosparql-assembler.html) to specify a spatial
dataset
+and then use [Fuseki Mod GeoSPARQL](fuseki-mod-geosparql.html) to configure an
endpoint to manage that dataset's spatial index.
+An alternative self-contained Fuseki package
+[jena-fuseki-geosparql](geosparql-fuseki.html) is provided (does not contain
the spatial index management).
+In either case, this page describes the GeoSPARQL supported features.
## Getting Started
GeoSPARQL Jena can be accessed as a library using Maven etc. from Maven
Central.
diff --git a/source/documentation/geosparql/fuseki-mod-geosparql.md
b/source/documentation/geosparql/fuseki-mod-geosparql.md
new file mode 100644
index 000000000..4c784221a
--- /dev/null
+++ b/source/documentation/geosparql/fuseki-mod-geosparql.md
@@ -0,0 +1,117 @@
+---
+title: GeoSPARQL Fuseki Module
+---
+
+The GeoSPARQL Fuseki Module features an endpoint to manage a dataset's spatial
index. The endpoint comes with an HTML view and a corresponding API.
+Spatial indexes need to be manually updated after modifications to the
underlying RDF data.
+The spatial indexer endpoint allows one to reindex specific graphs or all
graphs of an underlying dataset.
+Spatial datasets are generally configured using the [GeoSPARQL
Assembler](geosparql-assembler.html).
+
+The architecture is as follows: The Fuseki2 server in the Java module
`jena-fuseki-server` ships with the GeoSPARQL Fuseki Module in
`jena-fuseki-mod-geosparql`. The latter depends on `jena-geosparql` for
GeoSPARQL support.
+
+## Spatial Indexer Endpoint Configuration
+
+The following snippet summarizes how to declare a spatial indexer endpoint in
a Fuseki configuration.
+
+```turtle
+PREFIX fuseki: <http://jena.apache.org/fuseki#>
+
+<#ep-spatial-indexer> fuseki:name "spatial-indexer" ;
+ fuseki:operation fuseki:spatial-indexer ;
+ fuseki:allowedUsers "anne" . # Optional access control.
+```
+
+The spatial indexer endpoint needs to be registered with a service. The
following shows an example where the spatial indexer endpoint is registered
next to a usual query and update endpoint. Make sure to see Fuseki's
documentation about [Access Control
Lists](../fuseki2/fuseki-data-access-control.html#acl) for securing your
endpoints.
+
+```turtle
+<#service> a fuseki:Service ;
+ fuseki:name "ds" ;
+ fuseki:endpoint [ fuseki:operation fuseki:query ] ;
+ fuseki:endpoint [ fuseki:name "update" ; fuseki:operation fuseki:update ] ;
+
+ # This is the configuration for the spatial indexer endpoint:
+ fuseki:endpoint [
+ fuseki:name "spatial-indexer" ;
+ fuseki:operation fuseki:spatial-indexer ;
+ fuseki:allowedUsers "anne" . # Optional access control.
+ ] ;
+
+ # ... further configuration ...
+ fuseki:dataset <#your-spatial-dataset> ;
+ .
+
+# The dataset referenced by fuseki:dataset should be of type
"geosparql:GeosparqlDataset":
+# <#your-spatial-dataset> a geosparql:GeosparqlDataset ;
+# ...
+```
+
+## Spatial Indexer Web API
+
+* Access the spatial indexer web page.
+
+ ```bash
+ curl http://localhost:3030/ds/spatial-indexer
+ ```
+
+* Note, if access control is enabled, then curl's `-u` option (short for
`--user`) can be used to supply the credentials:
+
+ ```bash
+ curl http://localhost:3030/ds/spatial-indexer -u 'user:password'
+ ```
+
+* List available graphs. This API is used by the spatial indexer HTML view to
render the list of available graphs. The `keyword`, `limit`, and `offset`
parameters are optional. The `keyword` parameter performs a case-insensitive
substring match over graph URIs. The default graph and union graph constants
are members of this set and can also be passed to the `graph` option of the
`index` command. The union graph constant is thereby expanded to the set of all
*named* graphs - i.e. the set [...]
+
+ ```bash
+ curl -X POST
'http://localhost:3030/ds/spatial-indexer?command=graphs&offset=1&limit=10&keyword=graph'
+ ```
+
+ ```json
+ ["urn:x-arq:DefaultGraph","urn:x-arq:UnionGraph","https://example.org/graph";]
+ ```
+
+* Retrieve status information. Only a single indexing task can be active per
dataset.
+
+ ```bash
+ curl -X POST 'http://localhost:3030/ds/spatial-indexer?command=status'
+ ```
+
+ ```json
+ {"isIndexing":true,"isAborting":false,"time":1749320452197}
+ ```
+
+* Start a cleanup task. This removes dangling graph entries from the spatial
index. These are entries in the spatial index for which there is no longer a
corresponding graph in the dataset.
+
+ ```bash
+ curl -X POST 'http://localhost:3030/ds/spatial-indexer?command=clean'
+ ```
+
+* Start an indexing task. This request does not wait for indexing to complete.
+
+ ```bash
+ curl -X POST 'http://localhost:3030/ds/spatial-indexer?command=index'
+ ```
+
+* Index specific graphs using the `graphs` option. The value must be a JSON
array of strings with graph names.
+
+ ```bash
+ curl -X POST 'http://localhost:3030/ds/spatial-indexer?command=index' \
+ --data-urlencode
'graphs=["urn:x-arq:DefaultGraph","http://your.named/graph";]'
+ ```
+
+* Cancel a running indexing or clean task.
+
+ ```bash
+ curl -X POST 'http://localhost:3030/ds/spatial-indexer?command=cancel'
+ ```
+
+* If an index task failed, such as due to cancellation, then the `error` field
will contain a stack trace with information.
+
+ ```bash
+ curl -X POST 'http://localhost:3030/ds/spatial-indexer?command=status'
+ ```
+
+ ```json
+ {"isIndexing":false,"error":"java.lang.InterruptedException\n(stack
trace)\n","time":1749320601685}
+ ```
+
+
diff --git a/source/documentation/geosparql/geosparql-assembler.md
b/source/documentation/geosparql/geosparql-assembler.md
index 70fa1339a..e97d86525 100644
--- a/source/documentation/geosparql/geosparql-assembler.md
+++ b/source/documentation/geosparql/geosparql-assembler.md
@@ -37,15 +37,19 @@ PREFIX geosparql: <http://jena.apache.org/geosparql#>
fuseki:dataset <#geo_ds> .
<#geo_ds> rdf:type geosparql:geosparqlDataset ;
- geosparql:spatialIndexFile "DB/spatial.index";
+ geosparql:spatialIndexFile "run/databases/tdb2/mydb/spatial.index";
geosparql:dataset <#baseDataset> ;
+ geosparql:srsUri <http://www.opengis.net/def/crs/OGC/1.3/CRS84> ; # See
note below.
.
<#baseDataset> rdf:type tdb2:DatasetTDB2 ;
- tdb2:location "DB/" ;
+ tdb2:location "run/databases/tdb2/mydb" ;
.
```
+It is strongly advised to explicitly define a value for `geosparql:srsUri`.
The spatial reference system (SRS) URI is needed during the initial
construction of a spatial index. The SRS associated with an *existing* index
takes precedence over the assembler option. In order for a modified SRS
assembler configuration to take effect, the the existing persistent index file
(pointed to by `geosparql:spatialIndexFile`) needs to be manually deleted.
+If `geosparql:srsUri` is absent, then a value will be automatically computed
by scanning all available geometric data and randomly selecting from the most
prevalent SRS URIs. Scanning may take a while for large datasets.
+
It is possible to run with a data file loaded into memory and
a spatial in-memory index:
@@ -77,7 +81,9 @@ The full assembler properties with the default settings is:
```turtle
<#geo_ds> rdf:type geosparql:GeosparqlDataset ;
# Build in-memory is absent.
- geosparql:spatialIndexFile "spatial.index";
+ geosparql:spatialIndexFile "run/databases/tdb2/mydb/spatial.index" ;
+
+ geosparql:srsUri <http://www.opengis.net/def/crs/OGC/1.3/CRS84> ;
## Default settings. See documentation for meanings.
geosparql:inference true ;
@@ -93,3 +99,4 @@ The full assembler properties with the default settings is:
geosparql:dataset <#baseDataset> ;
.
```
+
