blob: 150468741960300d8b17a25e280035bdc880d961 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<title>Apache Jena - ARQ - Basic Federated SPARQL Query</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-icons.css" rel="stylesheet" media="screen"><link rel="stylesheet" type="text/css" href="https://jena.apache.org/sass/jena.1b17c39a117e22b46db4c66f6395dc27c134a60377d87d2d5745b8600eb69722.css" integrity="sha256-GxfDmhF&#43;IrRttMZvY5XcJ8E0pgN32H0tV0W4YA62lyI=">
<link rel="shortcut icon" href="/images/favicon.ico" />
</head>
<body>
<nav class="navbar navbar-expand-lg bg-body-tertiary" role="navigation">
<div class="container">
<div class="navbar-header">
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></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" id="navbarNav">
<ul class="navbar-nav me-auto mb-2 mb-lg-0">
<li id="homepage" class="nav-item"><a class="nav-link" href="/index.html"><span class="bi-house"></span> Home</a></li>
<li id="download" class="nav-item"><a class="nav-link" href="/download/index.cgi"><span class="bi-download"></span> Download</a></li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false"><span class="bi-journal"></span> Learn <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="dropdown-header">Tutorials</li>
<li><a class="dropdown-item" href="/tutorials/index.html">Overview</a></li>
<li><a class="dropdown-item" href="/documentation/fuseki2/index.html">Fuseki Triplestore</a></li>
<li><a class="dropdown-item" href="/documentation/notes/index.html">How-To's</a></li>
<li><a class="dropdown-item" href="/documentation/query/manipulating_sparql_using_arq.html">Manipulating SPARQL using ARQ</a></li>
<li><a class="dropdown-item" href="/tutorials/rdf_api.html">RDF core API tutorial</a></li>
<li><a class="dropdown-item" href="/tutorials/sparql.html">SPARQL tutorial</a></li>
<li><a class="dropdown-item" href="/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</a></li>
<li class="dropdown-divider"></li>
<li class="dropdown-header">References</li>
<li><a class="dropdown-item" href="/documentation/index.html">Overview</a></li>
<li><a class="dropdown-item" href="/documentation/query/index.html">ARQ (SPARQL)</a></li>
<li><a class="dropdown-item" href="/documentation/io/">RDF I/O</a></li>
<li><a class="dropdown-item" href="/documentation/assembler/index.html">Assembler</a></li>
<li><a class="dropdown-item" href="/documentation/tools/index.html">Command-line tools</a></li>
<li><a class="dropdown-item" href="/documentation/rdfs/">Data with RDFS Inferencing</a></li>
<li><a class="dropdown-item" href="/documentation/geosparql/index.html">GeoSPARQL</a></li>
<li><a class="dropdown-item" href="/documentation/inference/index.html">Inference API</a></li>
<li><a class="dropdown-item" href="/documentation/ontology/">Ontology API</a></li>
<li><a class="dropdown-item" href="/documentation/permissions/index.html">Permissions</a></li>
<li><a class="dropdown-item" href="/documentation/extras/querybuilder/index.html">Query Builder</a></li>
<li><a class="dropdown-item" href="/documentation/rdf/index.html">RDF API</a></li>
<li><a class="dropdown-item" href="/documentation/rdfconnection/">RDF Connection - SPARQL API</a></li>
<li><a class="dropdown-item" href="/documentation/rdfstar/index.html">RDF-star</a></li>
<li><a class="dropdown-item" href="/documentation/shacl/index.html">SHACL</a></li>
<li><a class="dropdown-item" href="/documentation/shex/index.html">ShEx</a></li>
<li><a class="dropdown-item" href="/documentation/tdb/index.html">TDB</a></li>
<li><a class="dropdown-item" href="/documentation/tdb2/index.html">TDB2</a></li>
<li><a class="dropdown-item" href="/documentation/query/text-query.html">Text Search</a></li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false"><span class="bi-journal-code"></span> Javadoc <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="/documentation/javadoc.html">All Javadoc</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/arq/">ARQ</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/fuseki2/">Fuseki</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/geosparql/">GeoSPARQL</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/jena/">Jena Core</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/permissions/">Permissions</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/extras/querybuilder/">Query Builder</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/shacl/">SHACL</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/tdb/">TDB</a></li>
<li><a class="dropdown-item" href="/documentation/javadoc/text/">Text Search</a></li>
</ul>
</li>
</ul>
<form class="d-flex" role="search" action="/search" method="GET">
<div class="input-group">
<input class="form-control border-end-0 border m-0" type="search" name="q" id="search-query" placeholder="Search...." aria-label="Search" style="width: 10rem;">
<button class="btn btn-outline-secondary border-start-0 border" type="submit">
<i class="bi-search"></i>
</button>
</div>
</form>
<ul class="navbar-nav">
<li id="ask" class="nav-item"><a class="nav-link" href="/help_and_support/index.html" title="Ask"><span class="bi-patch-question"></span><span class="text-body d-none d-xxl-inline"> Ask</span></a></li>
<li class="nav-item dropdown">
<a href="#" title="Get involved" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false"><span class="bi-megaphone"></span><span class="text-body d-none d-xxl-inline"> Get involved </span><b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="/getting_involved/index.html">Contribute</a></li>
<li><a class="dropdown-item" href="/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
<li class="dropdown-divider"></li>
<li class="dropdown-header">Project</li>
<li><a class="dropdown-item" href="/about_jena/about.html">About Jena</a></li>
<li><a class="dropdown-item" href="/about_jena/architecture.html">Architecture</a></li>
<li><a class="dropdown-item" href="/about_jena/citing.html">Citing</a></li>
<li><a class="dropdown-item" href="/about_jena/team.html">Project team</a></li>
<li><a class="dropdown-item" href="/about_jena/contributions.html">Related projects</a></li>
<li><a class="dropdown-item" href="/about_jena/roadmap.html">Roadmap</a></li>
<li><a class="dropdown-item" href="/about_jena/security-advisories.html">Security Advisories</a></li>
<li class="dropdown-divider"></li>
<li class="dropdown-header">ASF</li>
<li><a class="dropdown-item" href="https://www.apache.org/">Apache Software Foundation</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/licenses/LICENSE-2.0">License</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/security/">Security</a></li>
<li><a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
</ul>
</li>
<li class="nav-item" id="edit"><a class="nav-link" href="https://github.com/apache/jena-site/edit/main/source/documentation/query/service.md" title="Edit this page on GitHub"><span class="bi-pencil-square"></span><span class="text-body d-none d-xxl-inline"> Edit this page</span></a></li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-12">
<div id="breadcrumbs">
<ol class="breadcrumb mt-4 p-2 bg-body-tertiary">
<li class="breadcrumb-item"><a href='/documentation'>DOCUMENTATION</a></li>
<li class="breadcrumb-item"><a href='/documentation/query'>QUERY</a></li>
<li class="breadcrumb-item active">SERVICE.HTML</li>
</ol>
</div>
<h1 class="title">ARQ - Basic Federated SPARQL Query</h1>
<main class="d-flex flex-xl-row flex-column">
<aside class="text-muted align-self-start mb-3 p-0 d-xl-none d-block">
<h2 class="h6 sticky-top m-0 p-2 bg-body-tertiary">On this page</h2>
<nav id="TableOfContents">
<ul>
<li><a href="#syntax">Syntax</a></li>
<li><a href="#algebra">Algebra</a></li>
<li><a href="#performance-considerations">Performance Considerations</a></li>
<li><a href="#controlling-service-requests">Controlling <code>SERVICE</code> requests.</a>
<ul>
<li>
<ul>
<li><a href="#arqhttpserviceallowed"><code>arq:httpServiceAllowed</code></a></li>
<li><a href="#arqhttpqueryclient"><code>arq:httpQueryClient</code></a></li>
<li><a href="#arqhttpservicesendmode"><code>arq:httpServiceSendMode</code></a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#old-context-setting">Old Context setting</a>
<ul>
<li>
<ul>
<li><a href="#srvquerytimeout"><code>srv:queryTimeout</code></a></li>
<li><a href="#srvquerycompression"><code>srv:queryCompression</code></a></li>
<li><a href="#srvqueryclient"><code>srv:queryClient</code></a></li>
<li><a href="#srvservicecontext"><code>srv:serviceContext</code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</aside>
<article class="flex-column me-lg-4">
<p>There are already ways to access remote RDF data. The simplest is
to read a document which is an RDF graph and query it. Another way
is with the
<a href="http://www.w3.org/TR/rdf-sparql-protocol/">SPARQL protocol</a> which
allows a query to be sent to a remote service endpoint and the
results sent back (in RDF, or an
<a href="http://www.w3.org/TR/rdf-sparql-XMLres/">XML-based results format</a>
or even a <a href="http://www.w3.org/TR/rdf-sparql-json-res/">JSON one</a>).</p>
<p><code>SERVICE</code> is a feature of SPARQL 1.1 that allows an executing query
to make a SPARQL protocol to another SPARQL endpoint.</p>
<h2 id="syntax">Syntax</h2>
<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sparql" data-lang="sparql"><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">PREFIX</span> : <span style="color:#a0a000">&lt;http://example/&gt;</span>
</span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">PREFIX</span> <span style="color:#00f;font-weight:bold">dc</span>: <span style="color:#a0a000">&lt;http://purl.org/dc/elements/1.1/&gt;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">SELECT</span> <span style="color:#b8860b">?a</span>
</span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">FROM</span> <span style="color:#a0a000">&lt;mybooks.rdf&gt;</span>
</span></span><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span> <span style="color:#b8860b">?b</span> <span style="color:#00f;font-weight:bold">dc</span>:<span style="color:#008000;font-weight:bold">title</span> <span style="color:#b8860b">?title</span> .
</span></span><span style="display:flex;"><span> <span style="color:#a2f;font-weight:bold">SERVICE</span> <span style="color:#a0a000">&lt;http://sparql.org/books&gt;</span>
</span></span><span style="display:flex;"><span> { <span style="color:#b8860b">?s</span> <span style="color:#00f;font-weight:bold">dc</span>:<span style="color:#008000;font-weight:bold">title</span> <span style="color:#b8860b">?title</span> . <span style="color:#b8860b">?s</span> <span style="color:#00f;font-weight:bold">dc</span>:<span style="color:#008000;font-weight:bold">creator</span> <span style="color:#b8860b">?a</span> }
</span></span><span style="display:flex;"><span>}
</span></span></code></pre></div><h2 id="algebra">Algebra</h2>
<p>There is an operator in the algebra.</p>
<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sparql" data-lang="sparql"><span style="display:flex;"><span>(<span style="color:#a2f;font-weight:bold">prefix</span> ((<span style="color:#00f;font-weight:bold">dc</span>: <span style="color:#a0a000">&lt;http://purl.org/dc/elements/1.1/&gt;</span>))
</span></span><span style="display:flex;"><span> (<span style="">project</span> (<span style="color:#b8860b">?a</span>)
</span></span><span style="display:flex;"><span> (<span style="">jo</span><span style="color:#a2f;font-weight:bold">in</span>
</span></span><span style="display:flex;"><span> (<span style="">BGP</span> [<span style="">triple</span> <span style="color:#b8860b">?b</span> <span style="color:#00f;font-weight:bold">dc</span>:<span style="color:#008000;font-weight:bold">title</span> <span style="color:#b8860b">?title</span>])
</span></span><span style="display:flex;"><span> (<span style="color:#a2f;font-weight:bold">service</span> <span style="color:#a0a000">&lt;http://sparql.org/books&gt;</span>
</span></span><span style="display:flex;"><span> (<span style="">BGP</span>
</span></span><span style="display:flex;"><span> [<span style="">triple</span> <span style="color:#b8860b">?s</span> <span style="color:#00f;font-weight:bold">dc</span>:<span style="color:#008000;font-weight:bold">title</span> <span style="color:#b8860b">?title</span>]
</span></span><span style="display:flex;"><span> [<span style="">triple</span> <span style="color:#b8860b">?s</span> <span style="color:#00f;font-weight:bold">dc</span>:<span style="color:#008000;font-weight:bold">creator</span> <span style="color:#b8860b">?a</span>]
</span></span><span style="display:flex;"><span> ))
</span></span><span style="display:flex;"><span> )))
</span></span></code></pre></div><h2 id="performance-considerations">Performance Considerations</h2>
<p>This feature is a basic building block to allow remote access in
the middle of a query, not a general solution to the issues in
distributed query evaluation. The algebra operation is executed
without regard to how selective the pattern is. So the order of the
query will affect the speed of execution. Because it involves HTTP
operations, asking the query in the right order matters a lot.
Don&rsquo;t ask for the whole of a bookstore just to find a book whose
title comes from a local RDF file - ask the bookshop a query with
the title already bound from earlier in the query.</p>
<h2 id="controlling-service-requests">Controlling <code>SERVICE</code> requests.</h2>
<p>The <code>SERVICE</code> operation in a SPARQL query may be configured via the Context.
The values for configuration can be set in the global context (accessed via
<code>ARQ.getContext()</code>) or in the per-query execution context.</p>
<p>The prefix <code>arq:</code> is <code>&lt;http://jena.apache.org/ARQ#&gt;</code>.</p>
<table>
<thead>
<tr>
<th>Symbol</th>
<th>Java Constant</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>arq:httpServiceAllowed</code></td>
<td><code>ARQ.httpServiceAllowed</code></td>
<td>true</td>
</tr>
<tr>
<td><code>arq:httpQueryClient</code></td>
<td><code>ARQ.httpQueryClient</code></td>
<td>System default.</td>
</tr>
<tr>
<td><code>arq:httpServiceSendMode</code></td>
<td>`ARQ.httpServiceSendMode</td>
<td>unset</td>
</tr>
</tbody>
</table>
<h4 id="arqhttpserviceallowed"><code>arq:httpServiceAllowed</code></h4>
<p>This setting can be used to disable execution of any SERVICE request in query.
Set to &ldquo;false&rdquo; to prohibit SERVICE requests.</p>
<h4 id="arqhttpqueryclient"><code>arq:httpQueryClient</code></h4>
<p>The java.net.http HttpClient object to use for SERVICE execution.</p>
<h4 id="arqhttpservicesendmode"><code>arq:httpServiceSendMode</code></h4>
<p>The HTTP operation to use. The value is a string or a <code>QuerySendMode</code> object.</p>
<p>String settings are:</p>
<table>
<thead>
<tr>
<th>Setting</th>
<th>Effect</th>
</tr>
</thead>
<tbody>
<tr>
<td>&ldquo;POST&rdquo;</td>
<td>Use HTTP POST. Same as &ldquo;asPost&rdquo;.</td>
</tr>
<tr>
<td>&ldquo;GET&rdquo;</td>
<td>Use HTTP GET unconditionally. Same as &ldquo;asGetAlways&rdquo;.</td>
</tr>
<tr>
<td>&ldquo;asGetAlways&rdquo;</td>
<td>Use HTTP GET.</td>
</tr>
<tr>
<td>&ldquo;asGetWithLimitBody&rdquo;</td>
<td>Use HTTP GET upto a size limit (usually 2kbytes).</td>
</tr>
<tr>
<td>&ldquo;asGetWithLimitForm&rdquo;</td>
<td>Use HTTP GET upto a size limit (usually 2kbytes), and use a HTML form for the query.</td>
</tr>
<tr>
<td>&ldquo;asPostForm&rdquo;</td>
<td>Use HTTP POST and use an HTML form for the query.</td>
</tr>
<tr>
<td>&ldquo;asPost&rdquo;</td>
<td>Use HTTP POST.</td>
</tr>
</tbody>
</table>
<h2 id="old-context-setting">Old Context setting</h2>
<p>Old settings are honored where possible but should not be used:</p>
<p>The prefix <code>srv:</code> is the IRI <code>&lt;http://jena.hpl.hp.com/Service#&gt;</code>.</p>
<table>
<thead>
<tr>
<th>Symbol</th>
<th>Usage</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>srv:queryTimeout</code></td>
<td>Set timeouts</td>
<td>none</td>
</tr>
<tr>
<td><code>srv:queryCompression</code></td>
<td>Enable use of deflation and GZip</td>
<td>true</td>
</tr>
<tr>
<td><code>srv:queryClient</code></td>
<td>Enable use of a specific client</td>
<td>none</td>
</tr>
<tr>
<td><code>srv:serviceContext</code></td>
<td>Per-endpoint configuration</td>
<td>none</td>
</tr>
</tbody>
</table>
<h4 id="srvquerytimeout"><code>srv:queryTimeout</code></h4>
<p>As documented above.</p>
<h4 id="srvquerycompression"><code>srv:queryCompression</code></h4>
<p>Sets the flag for use of deflation and GZip.</p>
<p>Boolean: True indicates that gzip compressed data is acceptable.</p>
<h4 id="srvqueryclient"><code>srv:queryClient</code></h4>
<p>Enable use of a specific client</p>
<p>Provides a slot for a specific <a href="https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/client/HttpClient.html">HttpClient</a> for use with a specific <code>SERVICE</code></p>
<h4 id="srvservicecontext"><code>srv:serviceContext</code></h4>
<p>Provides a mechanism to override system context settings on a per URI basis.</p>
<p>The value is a <code>Map&lt;String,Context&gt;</code> where the map key is the URI of the service endpoint, and the <code>Context</code> is a set of values to override the default values.</p>
<p>If a context is provided for the URI, the system context is copied and the
context for the URI is used to set specific values. This ensures that any URI
specific settings will be used.</p>
</article>
<aside class="text-muted align-self-start mb-3 mb-xl-5 p-0 d-none d-xl-flex flex-column sticky-top">
<h2 class="h6 sticky-top m-0 p-2 bg-body-tertiary">On this page</h2>
<nav id="TableOfContents">
<ul>
<li><a href="#syntax">Syntax</a></li>
<li><a href="#algebra">Algebra</a></li>
<li><a href="#performance-considerations">Performance Considerations</a></li>
<li><a href="#controlling-service-requests">Controlling <code>SERVICE</code> requests.</a>
<ul>
<li>
<ul>
<li><a href="#arqhttpserviceallowed"><code>arq:httpServiceAllowed</code></a></li>
<li><a href="#arqhttpqueryclient"><code>arq:httpQueryClient</code></a></li>
<li><a href="#arqhttpservicesendmode"><code>arq:httpServiceSendMode</code></a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#old-context-setting">Old Context setting</a>
<ul>
<li>
<ul>
<li><a href="#srvquerytimeout"><code>srv:queryTimeout</code></a></li>
<li><a href="#srvquerycompression"><code>srv:queryCompression</code></a></li>
<li><a href="#srvqueryclient"><code>srv:queryClient</code></a></li>
<li><a href="#srvservicecontext"><code>srv:serviceContext</code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</aside>
</main>
</div>
</div>
</div>
<footer class="bd-footer py-4 py-md-5 mt-4 mt-lg-5 bg-body-tertiary">
<div class="container" style="font-size:80%" >
<p>
Copyright &copy; 2011&ndash;2024 The Apache Software Foundation, Licensed under the
<a href="https://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 src="/js/popper.min.js.js" type="text/javascript"></script>
<script src="/js/bootstrap.min.js" type="text/javascript"></script>
<script src="/js/improve.js" type="text/javascript"></script>
<script type="text/javascript">
(function() {
'use strict'
const links = document.querySelectorAll(`a[href="${window.location.pathname}"]`)
if (links !== undefined && links !== null) {
for (const link of links) {
link.classList.add('active')
let parentElement = link.parentElement
let count = 0
const levelsLimit = 4
while (['UL', 'LI'].includes(parentElement.tagName) && count <= levelsLimit) {
if (parentElement.tagName === 'LI') {
parentElement.querySelector('a:first-child').classList.add('active')
}
parentElement = parentElement.parentElement
count++
}
}
}
})()
</script>
</body>
</html>