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>
