blob: 6b7362722a78314a688ec18e06d83e9a5d07b265 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<title>Apache Jena - Apache Jena SPARQL APIs</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 href="/css/jena.css" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="/images/favicon.ico" />
<script src="https://code.jquery.com/jquery-2.2.4.min.js"
integrity="sha256-BbhdlvQf/xTY9gja0Dq3HiwQF8LaCRTXxZKRutelT44="
crossorigin="anonymous"></script>
<script src="/js/jena-navigation.js" type="text/javascript"></script>
<script src="/js/bootstrap.min.js" type="text/javascript"></script>
<script src="/js/improve.js" type="text/javascript"></script>
</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.cgi"><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="/documentation/fuseki2/index.html">Fuseki Triplestore</a></li>
<li><a href="/documentation/notes/index.html">How-To's</a></li>
<li><a href="/documentation/query/manipulating_sparql_using_arq.html">Manipulating SPARQL using ARQ</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="/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</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/query/index.html">ARQ (SPARQL)</a></li>
<li><a href="/documentation/assembler/index.html">Assembler</a></li>
<li><a href="/documentation/tools/index.html">Command-line tools</a></li>
<li><a href="/documentation/rdfs/">Data with RDFS Inferencing</a></li>
<li><a href="/documentation/geosparql/index.html">GeoSPARQL</a></li>
<li><a href="/documentation/inference/index.html">Inference API</a></li>
<li><a href="/documentation/javadoc.html">Javadoc</a></li>
<li><a href="/documentation/ontology/">Ontology API</a></li>
<li><a href="/documentation/permissions/index.html">Permissions</a></li>
<li><a href="/documentation/extras/querybuilder/index.html">Query Builder</a></li>
<li><a href="/documentation/rdf/index.html">RDF API</a></li>
<li><a href="/documentation/rdfconnection/">RDF Connection - SPARQL API</a></li>
<li><a href="/documentation/io/">RDF I/O</a></li>
<li><a href="/documentation/rdfstar/index.html">RDF-star</a></li>
<li><a href="/documentation/shacl/index.html">SHACL</a></li>
<li><a href="/documentation/shex/index.html">ShEx</a></li>
<li><a href="/documentation/jdbc/index.html">SPARQL over JDBC</a></li>
<li><a href="/documentation/tdb/index.html">TDB</a></li>
<li><a href="/documentation/tdb2/index.html">TDB2</a></li>
<li><a href="/documentation/query/text-query.html">Text Search</a></li>
</ul>
</li>
<li class="drop down">
<a href="#" class="dropdown-toggle" data-toggle="dropdown"><span class="glyphicon glyphicon-book"></span> Javadoc <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="/documentation/javadoc.html">All Javadoc</a></li>
<li><a href="/documentation/javadoc/arq/">ARQ</a></li>
<li><a href="/documentation/javadoc_elephas.html">Elephas</a></li>
<li><a href="/documentation/javadoc/fuseki2/">Fuseki</a></li>
<li><a href="/documentation/javadoc/geosparql/">GeoSPARQL</a></li>
<li><a href="/documentation/javadoc/jdbc/">JDBC</a></li>
<li><a href="/documentation/javadoc/jena/">Jena Core</a></li>
<li><a href="/documentation/javadoc/permissions/">Permissions</a></li>
<li><a href="/documentation/javadoc/extras/querybuilder/">Query Builder</a></li>
<li><a href="/documentation/javadoc/shacl/">SHACL</a></li>
<li><a href="/documentation/javadoc/tdb/">TDB</a></li>
<li><a href="/documentation/javadoc/text/">Text Search</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/architecture.html">Architecture</a></li>
<li><a href="/about_jena/citing.html">Citing</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><a href="/about_jena/roadmap.html">Roadmap</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/foundation/sponsorship.html">Become a Sponsor</a></li>
<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
<li><a href="http://www.apache.org/security/">Security</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
</ul>
</li>
<li id="edit"><a href="https://github.com/apache/jena-site/edit/main/source/documentation/sparql-apis/__index.md" title="Edit this page on GitHub"><span class="glyphicon glyphicon-pencil"></span> Edit this page</a></li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-12">
<div id="breadcrumbs">
<ol class="breadcrumb">
<li><a href='/documentation'>DOCUMENTATION</a></li>
<li class="active">SPARQL APIS</li>
</ol>
</div>
<h1 class="title">Apache Jena SPARQL APIs</h1>
<p>Jump to the &ldquo;<a href="#changes">Changes</a>&rdquo; section.</p>
<h2 id="overview">Overview</h2>
<p>The SPARQL specifications provide
<a href="https://www.w3.org/TR/sparql11-query/">query</a>,
<a href="https://www.w3.org/TR/sparql11-update/">update</a> and the
<a href="https://www.w3.org/TR/sparql11-http-rdf-update/">graph store protocol</a> (GSP).</p>
<p>For working with RDF data:</p>
<table>
<thead>
<tr>
<th>API</th>
<th>GPI</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Model</code></td>
<td><code>Graph</code></td>
</tr>
<tr>
<td><code>Statement</code></td>
<td><code>Triple</code></td>
</tr>
<tr>
<td><code>Resource</code></td>
<td><code>Node</code></td>
</tr>
<tr>
<td><code>Literal</code></td>
<td><code>Node</code></td>
</tr>
<tr>
<td><code>String</code></td>
<td><code>Var</code></td>
</tr>
<tr>
<td><code>Dataset</code></td>
<td><code>DatasetGraph</code></td>
</tr>
<tr>
<td></td>
<td><code>Quad</code></td>
</tr>
</tbody>
</table>
<p>and for SPARQL,</p>
<table>
<thead>
<tr>
<th>API</th>
<th>GPI</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>RDFConnection</code></td>
<td><code>RDFLink</code></td>
</tr>
<tr>
<td><code>QueryExecution</code></td>
<td><code>QueryExec</code></td>
</tr>
<tr>
<td><code>UpdateExecution</code></td>
<td><code>UpdateExec</code></td>
</tr>
<tr>
<td><code>ResultSet</code></td>
<td><code>RowSet</code></td>
</tr>
<tr>
<td><code>ModelStore</code></td>
<td><code>GSP</code></td>
</tr>
</tbody>
</table>
<p>Jena provides a single interface, <a href="../rdfconnection"><code>RDFConnection</code></a> for
working with local and remote RDF data using these protocols in a unified way.
This is most useful for remote data because the setup to connect is more
complicated and can be done once and reused.</p>
<p>HTTP authentication support is provided, supporting both basic and digest
authentication in challenge-response scenarios. Most authentication setup is
abstracted away from the particualr HTTP client library Jena is using.</p>
<p>Applications can also use the various execution engines through
<code>QueryExecution</code>, <code>UpdateExecution</code> and <code>ModelStore</code>.</p>
<p>All the main implementations work at &ldquo;Graph SPI&rdquo; (GPI) level and an application
may wish to work with this lower level interface that implements generalized RDF
(i.e. a triple is any three nodes, including ones like variables, and subsystem
extension nodes).</p>
<p>The GPI version is the main machinery working at the storage and network level,
and the API version is an adapter to convert to the Model API and related
classes.</p>
<p><code>UpdateProcessor</code> is a legacy name for <code>UpdateExecution</code></p>
<p><code>GSP</code> provides the SPARQL Graph Store Protocol, including extensions for sending
and receiving datasets, rather than individual graphs.</p>
<p>Both API and GPI provide builders for detailed setup, particularly for remote
usage over HTTP and HTTPS where detailed control of the HTTP requests is
sometimes necessary to work with other triple stores.</p>
<p>Use of the builders is preferred to factories. Factory style functions for many
common usage patterns are retained in <code>QueryExecutionFactory</code>,
<code>UpdateExecutionFactory</code>. Note that any methods that involved Apache HttpClient
objects have been removed.</p>
<h2 id="changes">Changes from Jena 4.2.0 to Jena 4.3.0</h2>
<ul>
<li>
<p>Execution objects have a companion builder. This is especially important of
HTTP as there many configuration options that may be needed. Local use is
still covered by the existing <code>QueryExecutionFactory</code> as well as the new
<code>QueryExecutionBuilder</code>.</p>
</li>
<li>
<p>HTTP usage provided by the JDK <code>java.net.http</code> package, with challenge-based
authentication provided on top by Jena. <a href="./http-auth.html">See the authentiucation documentation</a>.</p>
</li>
<li>
<p>Authentication support is uniformly applied to query, update, GSP and <code>SERVICE</code>.</p>
</li>
<li>
<p>HTTP/2 support</p>
</li>
<li>
<p>Remove Apache HttpClient usage</p>
<ul>
<li>When using this for authentication, application code changes wil be
necessary.</li>
</ul>
</li>
<li>
<p>Deprecate modifying <code>QueryExecution</code> after it is built.</p>
</li>
<li>
<p>Substitution of variables for concrete values in query and update execution.
This is a form of paramterization that works in both local and remnote usage
(unlike &ldquo;initial bindings&rdquo; which are only available for local query execution).
See the <a href="#substitution">substitution section</a> section below.</p>
</li>
<li>
<p><code>HttpOp</code>, using <code>java.net.http.HttpClient</code>, is split into <code>HttpRDF</code> for
GET/POST/PUT/DELETE of graphs and datasets and new <code>HttpOp</code> for packaged-up
common patterns of HTTP usage.</p>
</li>
<li>
<p>The previous <code>HttpOp</code> is available as <code>HttpOp1</code> and Apache HttpClient is still
a dependency. Eventually, <code>HttpOp</code> and dependency on Apache HttpClient will be removed.</p>
</li>
<li>
<p>GSP - support for dataset operations as well as graphs (also supported by Fuseki).</p>
</li>
<li>
<p><code>DatasetAccessor</code>s removed - previously these were deprecated. <code>GSP</code> and
<code>ModelStore</code> are the replacement for remote operations. <code>RDFConnection</code> and
<code>RDFLink</code> provide APIs.</p>
</li>
</ul>
<h2 id="substitution">Substitution</h2>
<p>All query and update builders provide operations to use a query and substitute
variables for concrete RDF terms in the execution.</p>
<p>Unlike &ldquo;initial bindings&rdquo; substitution is provided in query and update builders
for both local and remote cases.</p>
<p>Substitution is always &ldquo;replace variable with RDF term&rdquo; in a query or update
that is correct syntax. This means it does not apply to <code>INSERT DATA</code> or <code>DELETE DATA</code> but can be used with <code>INSERT { ?s ?p ?o } WHERE {}</code> and
<code>DELETE { ?s ?p ?o } WHERE {}</code>.</p>
<p>Full example:
<a href="https://github.com/apache/jena/tree/main/jena-examples/src/main/java/arq/examples/ExQuerySubstitute_01.java">ExQuerySubstitute_01.java</a>.</p>
<pre><code> ResultSet resultSet1 = QueryExecution.dataset(dataset)
.query(prefixes+&quot;SELECT * { ?person foaf:name ?name }&quot;)
.substitution(&quot;name&quot;, name1)
.select();
ResultSetFormatter.out(resultSet1);
</code></pre><p>Substitution is to be preferred over &ldquo;initial bindings&rdquo; because it is clearly
defined and applies to both query and update in both local and remote uses.</p>
<p>&ldquo;Substitution&rdquo; and &ldquo;initial bindings&rdquo; are similar but not identical.</p>
<p>See also</p>
<ul>
<li><a href="documentation/query/parameterized-sparql-strings.html">Parameterized Queries</a></li>
<li><a href="https://jena.apache.org/documentation/extras/querybuilder/index.html">Jena Query Builder</a></li>
</ul>
<p>which provide different ways to build a query.</p>
<h2 id="ttrdfconnectiontt"><tt>RDFConnection</tt></h2>
<p><a href="../rdfconnection/">RDFConnection</a></p>
<pre><code> try ( RDFConnection conn = RDFConnectionRemote.service(dataURL).build()) {
conn.update(&quot;INSERT DATA{}&quot;);
conn.queryAsk(&quot;ASK{}&quot;);
}
</code></pre><p>or the less flexible:</p>
<pre><code> try ( RDFConnection conn = RDFConnection.connect(dataURL) ) {
conn.update(&quot;INSERT DATA{}&quot;);
conn.queryAsk(&quot;ASK{}&quot;);
}
</code></pre><h2 id="query-execution">Query Execution</h2>
<p>Builder Examples
Builders are reusable and modifiable after a &ldquo;build&rdquo; operation.</p>
<pre><code>Dataset dataset = ...
Query query = ...
try ( QueryExecution qExec = QueryExecution.create()
.dataset(dataset)
.query(query)
.build() ) {
ResultSet results = qExec.execSelect();
... use results ...
}
</code></pre><p>and remote calls:</p>
<pre><code>try ( QueryExecution qExec = QueryExecutionHTTP.service(&quot;http://....&quot;)
.query(query)
.build() ) {
ResultSet results = qExec.execSelect();
... use results ...
}
</code></pre><p>Factory Examples</p>
<pre><code> Dataset dataset = ...
Query query = ...
try ( QueryExecution qExec = QueryExecutionFactory.create(query, dataset) ) {
ResultSet results = qExec.execSelect();
... use results ...
}
</code></pre><p>More complex setup:</p>
<pre><code>// JDK HttpClient
HttpClient httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10)) // Timeout to connect
.followRedirects(Redirect.NORMAL)
.build();
try ( QueryExecution qExec = QueryExecutionHTTP.create()
.service(&quot;http:// ....&quot;)
.httpClient(httpClient)
.query(query)
.sendMode(QuerySendMode.asPost)
.timeout(30, TimeUnit.SECONDS) // Timeout of request
.build() ) {
ResultSet results = qExec.execSelect();
... use results ...
}
</code></pre><p>There is only one timeout setting for eacho HTTP query execution. The &ldquo;time to
connect&rdquo; is handled by the JDK <code>HttpClient</code>. Timeouts for local execution are
&ldquo;time to first result&rdquo; and &ldquo;time to all results&rdquo; as before.</p>
<h2 id="ttmodelstorett-and-ttgsptt"><tt>ModelStore</tt> and <tt>GSP</tt></h2>
<pre><code> Model model = ModelStore.service(&quot;http://fuseki/dataset&quot;).defaultGraph().GET();
</code></pre><pre><code> Graph graph = GSP.service(&quot;http://fuseki/dataset&quot;).defaultGraph().GET();
</code></pre><pre><code> Graph graph = ... ;
GSP.request(&quot;http://fuseki/dataset&quot;).graphName(&quot;http;//data/myGraph&quot;).POST(graph);
</code></pre><pre><code> DatasetGraph dataset = GSP.request(&quot;http://fuseki/dataset&quot;).getDataset();
</code></pre><h2 id="ttservicett"><tt>SERVICE</tt></h2>
<p><a href="../query/service.html">Old documentation </a> - configuration, especially for
authentication, has changed.</p>
<h2 id="service-configuration">SERVICE configuration</h2>
<p>See below for more on HTTP authentication with <code>SERVICE</code>.</p>
<p>The configuration of <code>SERVICE</code> operations has changed in Jena 4.3.0 and the
paramter names have changed.</p>
<table>
<thead>
<tr>
<th>Symbol</th>
<th>Java Constant</th>
<th>Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>arq:httpServiceAllowed</code></td>
<td><code>ARQ.httpServiceAllowed</code></td>
<td>False to disable</td>
</tr>
<tr>
<td><code>arq:serviceParams</code></td>
<td><code>ARQ.serviceParams</code></td>
<td>Map</td>
</tr>
<tr>
<td><code>arq:httpQueryTimeout</code></td>
<td><code>ARQ.httpQueryTimeout</code></td>
<td>Request timeout (time to completion)</td>
</tr>
<tr>
<td><code>arq:httpQueryClient</code></td>
<td><code>ARQ.httpQueryCient</code></td>
<td>An <code>java.net.http.HttpClient</code> object</td>
</tr>
<tr>
<td><code>arq:httpQueryCompression</code></td>
<td></td>
<td>no-op</td>
</tr>
</tbody>
</table>
<p>where <code>arq:</code> is prefix for <code>&lt;http://jena.apache.org/ARQ#&gt;</code>.</p>
<p>The timeout is now only for the overall request and manged by the HTTP client
code.</p>
<p>Compression of responses is not currently supported.</p>
<h2 id="customization-of-http-requests">Customization of HTTP requests</h2>
<p>There is a mechanism to modify HTTP requests to specific endpoints or to a
collection of endpoints with the same prefix.</p>
<p>For example, to add a header <code>X-Tracker</code> to each request to a particular server:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"> AtomicLong counter <span style="color:#666">=</span> <span style="color:#a2f;font-weight:bold">new</span> AtomicLong<span style="color:#666">(</span>0<span style="color:#666">);</span>
HttpRequestModifier modifier <span style="color:#666">=</span> <span style="color:#666">(</span>params<span style="color:#666">,</span> headers<span style="color:#666">)-&gt;{</span>
<span style="color:#0b0;font-weight:bold">long</span> x <span style="color:#666">=</span> counter<span style="color:#666">.</span><span style="color:#b44">incrementAndGet</span><span style="color:#666">();</span>
headers<span style="color:#666">.</span><span style="color:#b44">put</span><span style="color:#666">(</span><span style="color:#b44">&#34;X-Tracker&#34;</span><span style="color:#666">,</span> <span style="color:#b44">&#34;Call=&#34;</span><span style="color:#666">+</span>x<span style="color:#666">);</span>
<span style="color:#666">};</span>
<span style="color:#080;font-style:italic">// serverURL is the HTTP URL for the server or part of the server HTTP space.
</span><span style="color:#080;font-style:italic"></span> RegistryRequestModifier<span style="color:#666">.</span><span style="color:#b44">get</span><span style="color:#666">().</span><span style="color:#b44">addPrefix</span><span style="color:#666">(</span>serverURL<span style="color:#666">,</span> modifier<span style="color:#666">);</span>
</code></pre></div><p>The <code>RegistryRequestModifier</code> registry is checked on each HTTP operation. It
maps URLs or prefix of URLs to a function of interface <code>HttpRequestModifier</code>
which has access to the headers and the query string parameters of the request.</p>
<h2 id="auth">Authentication</h2>
<p><a href="./http-auth.html">Documentation for authentication</a>.</p>
</div>
</div>
</div>
<footer class="footer">
<div class="container" style="font-size:80%" >
<p>
Copyright &copy; 2011&ndash;2022 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.
<br/>
<a href="https://privacy.apache.org/policies/privacy-policy-public.html"
>Apache Software Foundation Privacy Policy</a>.
</p>
</div>
</footer>
<script type="text/javascript">
var link = $('a[href="' + this.location.pathname + '"]');
if (link != undefined)
link.parents('li,ul').addClass('active');
</script>
</body>
</html>