You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2013/09/04 07:32:34 UTC
svn commit: r877239 - in /websites/staging/jena/trunk/content: ./
documentation/query/spatial-query.html
Author: buildbot
Date: Wed Sep 4 05:32:34 2013
New Revision: 877239
Log:
Staging update by buildbot for jena
Added:
websites/staging/jena/trunk/content/documentation/query/spatial-query.html
Modified:
websites/staging/jena/trunk/content/ (props changed)
Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Sep 4 05:32:34 2013
@@ -1 +1 @@
-1519633
+1519914
Added: websites/staging/jena/trunk/content/documentation/query/spatial-query.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/query/spatial-query.html (added)
+++ websites/staging/jena/trunk/content/documentation/query/spatial-query.html Wed Sep 4 05:32:34 2013
@@ -0,0 +1,415 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <title>Apache Jena - Spatial searches with SPARQL</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+ <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen">
+ <link href="/css/bootstrap-extension.css" rel="stylesheet" type="text/css">
+ <link rel="shortcut icon" href="/images/favicon.ico" />
+
+ <script src="http://code.jquery.com/jquery-2.0.3.min.js"></script>
+ <script src="/js/jena-navigation.js" type="text/javascript"></script>
+ <script src="/js/bootstrap.min.js" type="text/javascript"></script>
+ <script src="/js/breadcrumbs.js" type="text/javascript"></script>
+
+ <!-- Uncomment to enable code coloring <link href="/css/codehilite.css" rel="stylesheet" type="text/css"> -->
+
+</head>
+
+<body>
+
+
+
+<nav class="navbar navbar-default" role="navigation">
+<div class="container">
+ <div class="navbar-header">
+
+ <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-ex1-collapse">
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+ <a class="navbar-brand" href="/index.html">
+ <img class="logo-menu" src="/images/jena-logo/jena-logo-notext-small.png" alt="jena logo">Apache Jena</a>
+ </div>
+
+
+
+ <div class="collapse navbar-collapse navbar-ex1-collapse">
+ <ul class="nav navbar-nav">
+
+
+
+ <li id="homepage"><a href="/index.html"><span class="glyphicon glyphicon-home"></span> Home</a></li>
+ <li id="download"><a href="/download/index.html"><span class="glyphicon glyphicon-download-alt"></span> Download</a></li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-book"></span> Learn <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li class="dropdown-header">Tutorials</li>
+ <li><a href="/tutorials/index.html">Overview</a></li>
+ <li><a href="/tutorials/rdf_api.html">RDF core API tutorial</a></li>
+ <li><a href="/tutorials/sparql.html">SPARQL tutorial</a></li>
+ <li><a href="/documentation/query/manipulating_sparql_using_arq.html">Manipulating SPARQL using ARQ</a></li>
+ <li><a href="/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</a></li>
+ <li><a href="/documentation/notes/index.html">How-To's</a></li>
+ <li class="divider"></li>
+ <li class="dropdown-header">References</li>
+ <li><a href="/documentation/index.html">Overview</a></li>
+ <li><a href="/documentation/javadoc/">Javadoc</a></li>
+ <li><a href="/documentation/rdf/index.html">RDF API</a></li>
+ <li><a href="/documentation/io/">RDF I/O</a></li>
+ <li><a href="/documentation/query/index.html">ARQ (SPARQL)</a></li>
+ <li><a href="/documentation/query/text-query.html">Text Search</a></li>
+ <li><a href="/documentation/tdb/index.html">TDB</a></li>
+ <li><a href="/documentation/sdb/index.html">SDB</a></li>
+ <li><a href="/documentation/jdbc/index.html">SPARQL over JDBC</a></li>
+ <li><a href="/documentation/serving_data/index.html">Fuseki</a></li>
+ <li><a href="/documentation/assembler/index.html">Assembler</a></li>
+ <li><a href="/documentation/ontology/">Ontology API</a></li>
+ <li><a href="/documentation/inference/index.html">Inference API</a></li>
+ <li><a href="/documentation/tools/index.html">Command-line tools</a></li>
+ </ul>
+ </li>
+ <li id="ask"><a href="/help_and_support/index.html"><span class="glyphicon glyphicon-question-sign"></span> Ask</a></li>
+
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-bullhorn"></span> Get involved <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="/getting_involved/index.html">Contribute</a></li>
+ <li><a href="/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
+ <li class="divider"></li>
+ <li class="dropdown-header">Project</li>
+ <li><a href="/about_jena/about.html">About Jena</a></li>
+ <li><a href="/about_jena/roadmap.html">Roadmap</a></li>
+ <li><a href="/about_jena/architecture.html">Architecture</a></li>
+ <li><a href="/about_jena/team.html">Project team</a></li>
+ <li><a href="/about_jena/contributions.html">Related projects</a></li>
+ <li class="divider"></li>
+ <li class="dropdown-header">ASF</li>
+ <li><a href="http://www.apache.org/">Apache Software Foundation</a></li>
+ <li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </li>
+
+
+ </ul>
+ </div>
+</div>
+</nav>
+
+
+<div class="container">
+ <div class="row">
+ <div class="col-md-12">
+ <div id="breadcrumbs"></div>
+ <h1 class="title">Spatial searches with SPARQL</h1>
+ <p>It's an extension to Apache Jena ARQ, which combines SPARQL and simple spatial query.
+It gives applications the ability to perform simple spatial searches within SPARQL queries.
+Spatial indexes are additional information for accessing the RDF graph.</p>
+<p>The spatial index can be either <a href="http://lucene.apache.org/core">Apache Lucene</a> for a
+same-machine spatial index, or <a href="http://lucene.apache.org/solr/">Apache Solr</a>
+for a large scale enterprise search application.</p>
+<p>Some example code is <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-spatial/src/main/java/examples/">available here</a>.</p>
+<p><em>Illustration</em></p>
+<p>This query makes a spatial query for the places within 10 kilometers of Bristol UK (which as latitude/longitude of 51.46, 2.6).</p>
+<div class="codehilite"><pre><span class="n">PREFIX</span> <span class="n">spatial</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jena</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">spatial</span>#<span class="o">></span>
+<span class="n">PREFIX</span> <span class="n">rdfs</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>2000<span class="o">/</span>01<span class="o">/</span><span class="n">rdf</span><span class="o">-</span><span class="n">schema</span>#<span class="o">></span>
+
+<span class="n">SELECT</span> ?<span class="n">placeName</span>
+<span class="p">{</span>
+ ?<span class="n">place</span> <span class="n">spatial</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span>51<span class="p">.</span>46 2<span class="p">.</span>6 10 <span class="s">'km'</span><span class="p">)</span> <span class="p">.</span>
+ ?<span class="n">place</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">label</span> ?<span class="n">placeName</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="table-of-contents">Table of Contents</h2>
+<ul>
+<li><a href="#architecture">Architecture</a></li>
+<li><a href="#query-with-sparql">Query with SPARQL</a></li>
+<li><a href="#configuration">Configuration</a><ul>
+<li><a href="#text-dataset-assembler">Text Dataset Assembler</a></li>
+<li><a href="#configuration-by-code">Configuration by Code</a></li>
+</ul>
+</li>
+<li><a href="#working-with-fuseki">Working with Fuseki</a></li>
+<li><a href="#building-a-text-index">Building a Text Index</a></li>
+<li><a href="#deletion-of-indexed-entities">Deletion of Indexed Entities</a></li>
+<li><a href="#maven-dependency">Maven Dependency</a></li>
+</ul>
+<h2 id="how-to-use-it-by-code">How to Use it by Code</h2>
+<h3 id="create-spatial-dataset">Create Spatial Dataset</h3>
+<div class="codehilite"><pre><span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">jena</span><span class="p">.</span><span class="n">query</span><span class="p">.</span><span class="n">spatial</span><span class="p">.</span><span class="n">EntityDefinition</span>
+<span class="p">...</span>
+<span class="o">//</span> <span class="n">In</span> <span class="n">lucene</span><span class="p">,</span> "<span class="n">entityField</span>" <span class="n">stores</span> <span class="n">the</span> <span class="n">uri</span> <span class="n">of</span> <span class="n">the</span> <span class="n">subject</span> <span class="p">(</span><span class="n">e</span><span class="p">.</span><span class="n">g</span><span class="p">.</span> <span class="n">a</span> <span class="n">place</span><span class="p">),</span>
+<span class="o">//</span> <span class="k">while</span> "<span class="n">geoField</span>" <span class="n">holds</span> <span class="n">the</span> <span class="n">indexed</span> <span class="n">geo</span> <span class="n">data</span> <span class="p">(</span><span class="n">e</span><span class="p">.</span><span class="n">g</span><span class="p">.</span> <span class="n">latitude</span><span class="o">/</span><span class="n">longitude</span><span class="p">).</span>
+<span class="n">EntityDefinition</span> <span class="n">entDef</span> <span class="p">=</span> <span class="n">new</span> <span class="n">EntityDefinition</span><span class="p">(</span>"<span class="n">entityField</span>"<span class="p">,</span> "<span class="n">geoField</span>"<span class="p">);</span>
+
+<span class="o">//</span> <span class="n">index</span> <span class="n">in</span> <span class="n">File</span> <span class="n">system</span> <span class="p">(</span><span class="n">or</span> <span class="n">use</span> <span class="n">an</span> <span class="n">in</span><span class="o">-</span><span class="n">memory</span> <span class="n">one</span><span class="p">)</span>
+<span class="n">Directory</span> <span class="n">dir</span> <span class="p">=</span> <span class="n">FSDirectory</span><span class="p">.</span><span class="n">open</span><span class="p">(</span><span class="n">indexDir</span><span class="p">);</span>
+
+<span class="o">//</span> <span class="n">The</span> <span class="n">baseDataset</span> <span class="n">can</span> <span class="n">be</span> <span class="n">an</span> <span class="n">in</span><span class="o">-</span><span class="n">memory</span> <span class="n">or</span> <span class="n">TDB</span><span class="o">/</span><span class="n">SDB</span> <span class="n">file</span> <span class="n">based</span> <span class="n">one</span> <span class="n">which</span> <span class="n">contains</span> <span class="n">the</span> <span class="n">geo</span> <span class="n">data</span><span class="p">.</span> <span class="n">Join</span> <span class="n">together</span> <span class="n">into</span> <span class="n">a</span> <span class="n">dataset</span><span class="p">.</span>
+<span class="n">Dataset</span> <span class="n">spatialDataset</span> <span class="p">=</span> <span class="n">SpatialDatasetFactory</span><span class="p">.</span><span class="n">createLucene</span><span class="p">(</span><span class="n">baseDataset</span><span class="p">,</span> <span class="n">dir</span><span class="p">,</span> <span class="n">entDef</span><span class="p">);</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<h3 id="supported-geo-data-for-indexingquerying">Supported Geo Data for Indexing/Querying</h3>
+<h4 id="builtin-geo-prodicates">Builtin Geo Prodicates</h4>
+<p>There're mainly 2 types of RDF representation of geo data, which are both supported by jena-spatial:</p>
+<p><strong>1) Latitude/Longitude Format (in gonames, DBPedia and Linked Geo Data)</strong></p>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">prefix</span> <span class="n">geo</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>2003<span class="o">/</span>01<span class="o">/</span><span class="n">geo</span><span class="o">/</span><span class="n">wgs84_pos</span>#<span class="o">></span> <span class="p">.</span>
+<span class="p">:</span><span class="n">EGBB</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="p">:</span><span class="n">LargeAirport</span> <span class="p">;</span>
+ <span class="n">geo</span><span class="p">:</span><span class="n">lat</span> "52<span class="p">.</span>4539"^^<span class="n">xsd</span><span class="p">:</span><span class="n">float</span> <span class="p">;</span>
+ <span class="n">geo</span><span class="p">:</span><span class="n">long</span> "<span class="o">-</span>1<span class="p">.</span>74803"^^<span class="n">xsd</span><span class="p">:</span><span class="n">float</span> <span class="p">.</span>
+<span class="p">:</span><span class="n">EGBB_String</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="p">:</span><span class="n">LargeAirport</span> <span class="p">;</span>
+ <span class="n">geo</span><span class="p">:</span><span class="n">lat</span> "52<span class="p">.</span>4539" <span class="p">;</span>
+ <span class="n">geo</span><span class="p">:</span><span class="n">long</span> "<span class="o">-</span>1<span class="p">.</span>74803" <span class="p">.</span>
+</pre></div>
+
+
+<p><strong>2) Well Known Text (WKT) Literal (in DBPedia and Linked Geo Data)</strong></p>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">prefix</span> <span class="n">ogc</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">opengis</span><span class="p">.</span><span class="n">net</span><span class="o">/</span><span class="n">ont</span><span class="o">/</span><span class="n">geosparql</span>#<span class="o">></span> <span class="p">.</span>
+<span class="p">:</span><span class="n">node1000032677</span> <span class="n">a</span> <span class="p">:</span><span class="n">Geometry</span> <span class="p">;</span>
+ <span class="n">ogc</span><span class="p">:</span><span class="n">asWKT</span> "<span class="n">POINT</span><span class="p">(</span>7<span class="p">.</span>338818000000001 51<span class="p">.</span>4433324<span class="p">)</span>"^^<span class="n">ogc</span><span class="p">:</span><span class="n">wktLiteral</span> <span class="p">.</span>
+<span class="n">airports</span><span class="p">:</span><span class="n">EGBB_Fake_In_Box</span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">airports_sc</span><span class="p">:</span><span class="n">LargeAirport</span> <span class="p">;</span>
+ <span class="n">ogc</span><span class="p">:</span><span class="n">asWKT</span> "<span class="n">Polygon</span> <span class="p">((</span><span class="o">-</span>2<span class="p">.</span>0 51<span class="p">.</span>2<span class="p">,</span> 1<span class="p">.</span>0 51<span class="p">.</span>2<span class="p">,</span> 1<span class="p">.</span>0 51<span class="p">.</span>8<span class="p">,</span> <span class="o">-</span>2<span class="p">.</span>0 51<span class="p">.</span>8<span class="p">,</span> <span class="o">-</span>2<span class="p">.</span>0 51<span class="p">.</span>2<span class="p">))</span>"^^<span class="n">wkt</span><span class="p">:</span><span class="n">wktLiteral</span><span class="p">.</span>
+</pre></div>
+
+
+<p><strong>The builtin predicates that can be automatically processed by jena-spatial include: 1) <code>geo:lat</code>, <code>geo:long</code>; 2) <code>geo:geometry</code>, <code>ogc:asWKT</code>.</strong>
+For 2) WKT, DBPedia uses <code>geo:geometry</code>, while Linked Geo Data adopts <code>ogc:asWKT</code> and <code>geo:geometry</code>.</p>
+<p><strong>Important note</strong> In order to read geo data in 2) WKT literal format, jena-spatial uses <a href="http://tsusiatsoftware.net/jts/main.html">JTS Topology Suite</a>,
+which is under LGPL licence. jena-spatial <strong>does not</strong> make a hard dependency on JTS. In other words,
+if an end user just uses the feature of 1), there's no need to depend on JTS (i.e. nothing needs to be done). If he wants 2),
+he can make it by setting the <code>SpatialContextFactory</code> of <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-spatial/src/main/java/org/apache/jena/query/spatial/EntityDefinition.java">EntityDefinition</a> to <code>JtsSpatialContextFactory</code>,
+which is an optional choice): </p>
+<div class="codehilite"><pre><span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">jena</span><span class="p">.</span><span class="n">query</span><span class="p">.</span><span class="n">spatial</span><span class="p">.</span><span class="n">EntityDefinition</span>
+<span class="p">...</span>
+<span class="n">EntityDefinition</span> <span class="n">entDef</span> <span class="p">=</span> <span class="n">new</span> <span class="n">EntityDefinition</span><span class="p">(</span>"<span class="n">entityField</span>"<span class="p">,</span> "<span class="n">geoField</span>"<span class="p">);</span>
+
+<span class="o">//</span> <span class="n">use</span> <span class="n">JtsSpatialContextFactory</span> <span class="n">to</span> <span class="n">support</span> 2<span class="p">)</span> <span class="n">WKT</span> <span class="n">literals</span> <span class="p">(</span><span class="n">optional</span><span class="p">)</span>
+<span class="n">entDef</span><span class="p">.</span><span class="n">setSpatialContextFactory</span><span class="p">(</span>"<span class="n">com</span><span class="p">.</span><span class="n">spatial4j</span><span class="p">.</span><span class="n">core</span><span class="p">.</span><span class="n">context</span><span class="p">.</span><span class="n">jts</span><span class="p">.</span><span class="n">JtsSpatialContextFactory</span>"<span class="p">);</span>
+<span class="p">...</span>
+</pre></div>
+
+
+<h4 id="custom-geo-prodicates">Custom Geo Prodicates</h4>
+<p>However, there may be more predicates for other data sources for both 1) and 2).
+jena-spatial provides an interface for consuming all kinds of custom geo predicates.
+You can simply add predicates to let jena-spatial recognize them using <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-spatial/src/main/java/org/apache/jena/query/spatial/EntityDefinition.java">EntityDefinition</a>:</p>
+<div class="codehilite"><pre><span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">jena</span><span class="p">.</span><span class="n">query</span><span class="p">.</span><span class="n">spatial</span><span class="p">.</span><span class="n">EntityDefinition</span>
+<span class="p">...</span>
+
+<span class="n">EntityDefinition</span> <span class="n">entDef</span> <span class="p">=</span> <span class="n">new</span> <span class="n">EntityDefinition</span><span class="p">(</span>"<span class="n">entityField</span>"<span class="p">,</span> "<span class="n">geoField</span>"<span class="p">);</span>
+
+<span class="o">//</span> <span class="n">custom</span> <span class="n">geo</span> <span class="n">predicates</span> <span class="k">for</span> 1<span class="p">)</span> <span class="n">Latitude</span><span class="o">/</span><span class="n">Longitude</span> <span class="n">Format</span>
+<span class="n">Resource</span> <span class="n">lat_1</span> <span class="p">=</span> <span class="n">ResourceFactory</span><span class="p">.</span><span class="n">createResource</span><span class="p">(</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="o">/</span><span class="n">jena_example</span><span class="o">/</span>#<span class="n">latitude_1</span>"<span class="p">)</span> <span class="p">;</span>
+<span class="n">Resource</span> <span class="n">long_1</span> <span class="n">ResourceFactory</span><span class="p">.</span><span class="n">createResource</span><span class="p">(</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="o">/</span><span class="n">jena_example</span><span class="o">/</span>#<span class="n">longitude_1</span>"<span class="p">)</span> <span class="p">;</span>
+<span class="n">entDef</span><span class="p">.</span><span class="n">addSpatialPredicatePair</span><span class="p">(</span><span class="n">lat_1</span><span class="p">,</span> <span class="n">long_1</span><span class="p">)</span> <span class="p">;</span>
+
+<span class="o">//</span> <span class="n">custom</span> <span class="n">geo</span> <span class="n">predicates</span> <span class="k">for</span> <span class="n">Well</span> <span class="n">Known</span> <span class="n">Text</span> <span class="p">(</span><span class="n">WKT</span><span class="p">)</span> <span class="n">Literal</span>
+<span class="n">Resource</span> <span class="n">wkt_1</span> <span class="p">=</span> <span class="n">ResourceFactory</span><span class="p">.</span><span class="n">createResource</span><span class="p">(</span>"<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="o">/</span><span class="n">jena_example</span><span class="o">/</span>#<span class="n">wkt_1</span>"<span class="p">);</span>
+<span class="n">entDef</span><span class="p">.</span><span class="n">addWKTPredicate</span><span class="p">(</span> <span class="n">wkt_1</span> <span class="p">);</span>
+</pre></div>
+
+
+<p>See more supported <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-spatial/src/test/resources/geoarq-data-1.ttl">geo data examples</a></p>
+<h3 id="load-geo-data-into-spatial-dataset">Load Geo Data into Spatial Dataset</h3>
+<div class="codehilite"><pre><span class="n">spatialDataset</span><span class="p">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="p">.</span><span class="n">WRITE</span><span class="p">);</span>
+<span class="k">try</span> <span class="p">{</span>
+ <span class="n">Model</span> <span class="n">m</span> <span class="p">=</span> <span class="n">spatialDataset</span><span class="p">.</span><span class="n">getDefaultModel</span><span class="p">();</span>
+ <span class="n">RDFDataMgr</span><span class="p">.</span><span class="n">read</span><span class="p">(</span><span class="n">m</span><span class="p">,</span> <span class="n">file</span><span class="p">);</span>
+ <span class="n">spatialDataset</span><span class="p">.</span><span class="n">commit</span><span class="p">();</span>
+<span class="p">}</span> <span class="n">finally</span> <span class="p">{</span>
+ <span class="n">spatialDataset</span><span class="p">.</span><span class="k">end</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Now the spatial dataset is ready for spatial query.</p>
+<h2 id="property-function-library">Property Function Library</h2>
+<p>The prefix spatial is <code><http://jena.apache.org/spatial#></code>.</p>
+<table>
+<thead>
+<tr>
+<th> Property name </th>
+<th> Description </th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><em>?place</em> <strong>spatial:nearby</strong> <em>(latitude, longitude, radius [, units, limit])</em><br><em>?place</em> <strong>spatial:withinCircle</strong> <em>(latitude, longitude, radius [, units, limit])</em></td>
+<td>Query for the <em>?place</em> within the <em>radius</em> distance of the location of <em>(latitude, longitude)</em>. The distance <em>units</em> can be: "kilometers"/"km", "miles"/"mi", "meters"/"m", "centimeters"/"cm", "milimeters"/"mm" or "degrees"/"de", which are delivered as the optional strings (the default value is "kilometers"). <em>limit</em> is an optional integer parameter for the limit of the query results (if <em>limilt</em><0, return all query results).</td>
+</tr>
+<tr>
+<td><em>?place</em> <strong>spatial:withinBox</strong> <em>(latitude</em>min, longitude<em>min, latitude</em>max, longitude<em>max [, limit])</em></td>
+<td>Query for the <em>?place</em> within the box area of <em>(latitude</em>min, longitude<em>min, latitude</em>max, longitude<em>max)</em>.</td>
+</tr>
+<tr>
+<td><em>?place</em> <strong>spatial:intersectBox</strong> <em>(latitude</em>min, longitude<em>min, latitude</em>max, longitude<em>max [, limit])</em></td>
+<td>Query for the <em>?place</em> intersecting the box area of <em>(latitude</em>min, longitude<em>min, latitude</em>max, longitude<em>max)</em>.</td>
+</tr>
+<tr>
+<td><em>?place</em> <strong>spatial:north</strong> <em>(latitude, longitude [, limit])</em></td>
+<td>Query for the <em>?place</em> northing the location of <em>(latitude, longitude)</em>.</td>
+</tr>
+<tr>
+<td><em>?place</em> <strong>spatial:south</strong> <em>(latitude, longitude [, limit])</em></td>
+<td>Query for the <em>?place</em> southing the location of <em>(latitude, longitude)</em>.</td>
+</tr>
+<tr>
+<td><em>?place</em> <strong>spatial:west</strong> <em>(latitude, longitude [, limit])</em></td>
+<td>Query for the <em>?place</em> westing the location of <em>(latitude, longitude)</em>.</td>
+</tr>
+<tr>
+<td><em>?place</em> <strong>spatial:east</strong> <em>(latitude, longitude [, limit])</em></td>
+<td>Query for the <em>?place</em> easting the location of <em>(latitude, longitude)</em>.</td>
+</tr>
+</tbody>
+</table>
+<p>See <a href="http://edndoc.esri.com/arcsde/9.1/general_topics/understand_spatial_relations.htm">ESRIs docs on spatial relations</a></p>
+<h2 id="spatial-dataset-assembler">Spatial Dataset Assembler</h2>
+<p>The usual way to describe an index is with a <a href="http://jena.apache.org/documentation/assembler/index.html">Jena assembler description</a>. Configurations can also be built with <a href="#how-to-use-it-by-code">code</a>. The assembler describes a "spaital dataset" which has an underlying RDF dataset and a spatial index. The spatial index describes the spatial index technology (Lucene or Solr) and the details needed for for each.</p>
+<p>A spatial index has an "<a href="https://svn.apache.org/repos/asf/jena/trunk/jena-spatial/src/main/java/org/apache/jena/query/spatial/EntityDefinition.java">entity definition</a>" which defines the properties to index, the name of the lucene/solr field used for storing the URI itself (e.g. "entityField") and its geo information (e.g. latitude/longitude as "geoField"), and the custom geo predicates.</p>
+<p>For common RDF spatial query, only "entityField" and "geoField" are required with the <a href="#builtin-geo-predicates">builtin geo predicates</a> working well. More complex setups, with multiple <a href="#custom-geo-predicates">custom geo predicates</a> besides the two fields are possible.
+You also optionally use JtsSpatialContextFactory to support indexing WKT literals. </p>
+<p>Once setup this way, any data added to the spatial dataset is automatically indexed as well.</p>
+<p>The following is an example of a TDB dataset with a spatial index.</p>
+<div class="codehilite"><pre><span class="c">## Example of a TDB dataset and spatial index</span>
+
+<span class="p">@</span><span class="n">prefix</span> <span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="o">/</span><span class="n">jena_example</span><span class="o">/</span><span class="c">#> .</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">rdf</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>1999<span class="o">/</span>02<span class="o">/</span>22<span class="o">-</span><span class="n">rdf</span><span class="o">-</span><span class="n">syntax</span><span class="o">-</span><span class="n">ns</span><span class="c">#> .</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">rdfs</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>2000<span class="o">/</span>01<span class="o">/</span><span class="n">rdf</span><span class="o">-</span><span class="n">schema</span><span class="c">#> .</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">tdb</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jena</span><span class="p">.</span><span class="n">hpl</span><span class="p">.</span><span class="n">hp</span><span class="p">.</span><span class="n">com</span><span class="o">/</span>2008<span class="o">/</span><span class="n">tdb</span><span class="c">#> .</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">ja</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jena</span><span class="p">.</span><span class="n">hpl</span><span class="p">.</span><span class="n">hp</span><span class="p">.</span><span class="n">com</span><span class="o">/</span>2005<span class="o">/</span>11<span class="o">/</span><span class="n">Assembler</span><span class="c">#> .</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">spatial</span><span class="p">:</span> <span class="o"><</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jena</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">spatial</span><span class="c">#> .</span>
+
+<span class="c"># TDB</span>
+<span class="p">[]</span> <span class="n">ja</span><span class="p">:</span><span class="n">loadClass</span> <span class="s">"com.hp.hpl.jena.tdb.TDB"</span> <span class="p">.</span>
+<span class="n">tdb</span><span class="p">:</span><span class="n">DatasetTDB</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">subClassOf</span> <span class="n">ja</span><span class="p">:</span><span class="n">RDFDataset</span> <span class="p">.</span>
+<span class="n">tdb</span><span class="p">:</span><span class="n">GraphTDB</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">subClassOf</span> <span class="n">ja</span><span class="p">:</span><span class="n">Model</span> <span class="p">.</span>
+
+<span class="c"># Spatial</span>
+<span class="p">[]</span> <span class="n">ja</span><span class="p">:</span><span class="n">loadClass</span> <span class="s">"org.apache.jena.query.spatial.SpatialQuery"</span> <span class="p">.</span>
+<span class="n">spatial</span><span class="p">:</span><span class="n">SpatialtDataset</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">subClassOf</span> <span class="n">ja</span><span class="p">:</span><span class="n">RDFDataset</span> <span class="p">.</span>
+<span class="c">#spatial:SpatialIndexSolr rdfs:subClassOf spatial:SpatialIndex .</span>
+<span class="n">spatial</span><span class="p">:</span><span class="n">SpatialIndexLucene</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">subClassOf</span> <span class="n">spatial</span><span class="p">:</span><span class="n">SpatialIndex</span> <span class="p">.</span>
+
+<span class="c">## ---------------------------------------------------------------</span>
+<span class="c">## This URI must be fixed - it's used to assemble the spatial dataset.</span>
+
+<span class="p">:</span><span class="n">spatial_dataset</span> <span class="n">rdf</span><span class="p">:</span><span class="nb">type</span> <span class="n">spatial</span><span class="p">:</span><span class="n">SpatialDataset</span> <span class="p">;</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">dataset</span> <span class="o"><</span><span class="c">#dataset> ;</span>
+ <span class="c">##spaital:index <#indexSolr> ;</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="nb">index</span> <span class="o"><</span><span class="c">#indexLucene> ;</span>
+ <span class="p">.</span>
+
+<span class="o"><</span><span class="c">#dataset> rdf:type tdb:DatasetTDB ;</span>
+ <span class="n">tdb</span><span class="p">:</span><span class="n">location</span> <span class="s">"--mem--"</span> <span class="p">;</span>
+ <span class="n">tdb</span><span class="p">:</span><span class="n">unionDefaultGraph</span> <span class="nb">true</span> <span class="p">;</span>
+ <span class="p">.</span>
+
+<span class="o"><</span><span class="c">#indexLucene> a spatial:SpatialIndexLucene ;</span>
+ <span class="c">#spatial:directory <file:Lucene> ;</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">directory</span> <span class="s">"mem"</span> <span class="p">;</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">definition</span> <span class="o"><</span><span class="c">#definition> ;</span>
+ <span class="p">.</span>
+
+<span class="o"><</span><span class="c">#definition> a spatial:EntityDefinition ;</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">entityField</span> <span class="s">"uri"</span> <span class="p">;</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">geoField</span> <span class="s">"geo"</span> <span class="p">;</span>
+ <span class="c"># custom geo predicates for 1) Latitude/Longitude Format</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">hasSpatialPredicatePairs</span> <span class="p">(</span>
+ <span class="p">[</span> <span class="n">spatial</span><span class="p">:</span><span class="n">latitude</span> <span class="p">:</span><span class="n">latitude_1</span> <span class="p">;</span> <span class="n">spatial</span><span class="p">:</span><span class="n">longitude</span> <span class="p">:</span><span class="n">longitude_1</span> <span class="p">]</span>
+ <span class="p">[</span> <span class="n">spatial</span><span class="p">:</span><span class="n">latitude</span> <span class="p">:</span><span class="n">latitude_2</span> <span class="p">;</span> <span class="n">spatial</span><span class="p">:</span><span class="n">longitude</span> <span class="p">:</span><span class="n">longitude_2</span> <span class="p">]</span>
+ <span class="p">)</span> <span class="p">;</span>
+ <span class="c"># custom geo predicates for 2) Well Known Text (WKT) Literal</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">hasWKTPredicates</span> <span class="p">(:</span><span class="n">wkt_1</span> <span class="p">:</span><span class="n">wkt_2</span><span class="p">)</span> <span class="p">;</span>
+ <span class="c"># custom SpatialContextFactory for 2) Well Known Text (WKT) Literal</span>
+ <span class="n">spatial</span><span class="p">:</span><span class="n">spatialContextFactory</span>
+ <span class="s">"com.spatial4j.core.context.jts.JtsSpatialContextFactory"</span>
+ <span class="p">.</span>
+</pre></div>
+
+
+<p>then use code such as:</p>
+<div class="codehilite"><pre><span class="n">Dataset</span> <span class="n">spatialDataset</span> <span class="p">=</span> <span class="n">DatasetFactory</span><span class="p">.</span><span class="n">assemble</span><span class="p">(</span> "<span class="n">spatial</span><span class="o">-</span><span class="n">config</span><span class="p">.</span><span class="n">ttl</span>"<span class="p">,</span>
+ "<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="o">/</span><span class="n">jena_example</span><span class="o">/</span>#<span class="n">spatial_dataset</span>"<span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>Key here is that the assembler contains two dataset definitions, one for the spatial dataset, one for the base data. Therefore, the application needs to identify the text dataset by it's URI 'http://localhost/jena_example/#spatial_dataset'.</p>
+<h2 id="working-with-fuseki">Working with Fuseki</h2>
+<p>The Fuseki configuration simply points to the spatial dataset as the fuseki:dataset of the service.</p>
+<div class="codehilite"><pre><span class="o"><</span>#<span class="n">service_spatial_tdb</span><span class="o">></span> <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">fuseki</span><span class="p">:</span><span class="n">Service</span> <span class="p">;</span>
+ <span class="n">rdfs</span><span class="p">:</span><span class="n">label</span> "<span class="n">TDB</span><span class="o">/</span><span class="n">spatial</span> <span class="n">service</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">name</span> "<span class="n">ds</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">serviceQuery</span> "<span class="n">query</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">serviceQuery</span> "<span class="n">sparql</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">serviceUpdate</span> "<span class="n">update</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">serviceUpload</span> "<span class="n">upload</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">serviceReadGraphStore</span> "<span class="n">get</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">serviceReadWriteGraphStore</span> "<span class="n">data</span>" <span class="p">;</span>
+ <span class="n">fuseki</span><span class="p">:</span><span class="n">dataset</span> <span class="p">:</span><span class="n">spatial_dataset</span> <span class="p">;</span>
+</pre></div>
+
+
+<h2 id="building-a-spatial-index">Building a Spatial Index</h2>
+<p>When working at scale, or when preparing a published, read-only, SPARQL service, creating the index by loading the spatial dataset is impractical. The index and the dataset can be built using command line tools in two steps: first load the RDF data, second create an index from the existing RDF dataset.</p>
+<p>Build the TDB dataset:</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">cp</span> $<span class="n">FUSEKI_HOME</span><span class="o">/</span><span class="n">fuseki</span><span class="o">-</span><span class="n">server</span><span class="p">.</span><span class="n">jar</span> <span class="n">tdb</span><span class="p">.</span><span class="n">tdbloader</span> <span class="o">--</span><span class="n">tdb</span><span class="p">=</span><span class="n">assembler_file</span> <span class="n">data_file</span>
+</pre></div>
+
+
+<p>using the copy of TDB included with Fuseki. Alternatively, use one of the TDB utilities tdbloader or tdbloader2:</p>
+<div class="codehilite"><pre>$<span class="n">JENA_HOME</span><span class="o">/</span><span class="n">bin</span><span class="o">/</span><span class="n">tdbloader</span> <span class="o">--</span><span class="n">loc</span><span class="p">=</span><span class="n">directory</span> <span class="n">data_file</span>
+</pre></div>
+
+
+<p>then build the spatial index with the jena.spatialindexer:</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">cp</span> <span class="n">jena</span><span class="o">-</span><span class="n">spatial</span><span class="p">.</span><span class="n">jar</span> <span class="n">jena</span><span class="p">.</span><span class="n">spatialindexer</span> <span class="o">--</span><span class="n">desc</span><span class="p">=</span><span class="n">assembler_file</span>
+</pre></div>
+ </div>
+</div>
+
+</div><!--/.container -->
+
+ <footer class="footer">
+ <div class="container">
+ <p>Copyright © 2011–2013 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ </p>
+ <p>
+ Apache Jena, Jena, the Apache Jena project logo,
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </footer>
+
+
+</body>
+</html>