content/documentation/query/app_api.html - jena-site - Git at Google

 <!DOCTYPE html>
 <html lang="en">
 <head>


     <title>Apache Jena - ARQ - Application API</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/query/app_api.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><a href='/documentation/query'>QUERY</a></li>


                 <li class="active">APP API</li>


 </ol>


             </div>
             <h1 class="title">ARQ - Application API</h1>

 	<p>The application API is in the package <code>org.apache.jena.query</code>.</p>
 <p>Other packages contain various parts of the system (execution
 engine, parsers, testing etc). Most applications will only need to
 use the main package. Only applications wishing to programmatically
 build queries or modify the behaviour of the query engine need to
 use the others packages directly.</p>
 <h2 id="key-classes">Key Classes</h2>
 <p>The package <code>org.apache.jena.query</code> is the main application
 package.</p>
 <ul>
 <li><code>Query</code> - a class that represents the application query. It is
 a container for all the details of the query. Objects of class
 Query are normally created by calling one of the methods of
 <code>QueryFactory</code> methods which provide access to the various parsers.</li>
 <li><code>QueryExecution</code> - represents one execution of a query.</li>
 <li><code>QueryExecutionFactory</code> - a place to get <code>QueryExecution</code> instances.</li>
 <li><code>DatasetFactory</code> - a place to make datasets.</li>
 <li>For SELECT queries:
 <ul>
 <li><code>QuerySolution</code> - A single solution to the query.</li>
 <li><code>ResultSet</code> - All the QuerySolutions. An iterator.</li>
 <li><code>ResultSetFormatter</code> - turn a ResultSet into various forms;
 into json, text, or as plain XML.</li>
 </ul>
 </li>
 </ul>
 <h2 id="select-queries">SELECT queries</h2>
 <p>The basic steps in making a SELECT query are outlined in the
 example below. A query is created from a string using the
 <code>QueryFactory</code>. The query and model or RDF dataset to be queried
 are then passed to <code>QueryExecutionFactory</code> to produce an instance
 of a query execution. <code>QueryExecution</code> objects are <code>java.lang.AutoCloseable</code>
 and can be used in try-resource. Result are handled in a loop and finally the
 query execution is closed.</p>
 <pre><code>  import org.apache.jena.query.* ;
   Model model = ... ;
   String queryString = &quot; .... &quot; ;
   Query query = QueryFactory.create(queryString) ;
   try (QueryExecution qexec = QueryExecutionFactory.create(query, model)) {
     ResultSet results = qexec.execSelect() ;
     for ( ; results.hasNext() ; )
     {
       QuerySolution soln = results.nextSolution() ;
       RDFNode x = soln.get(&quot;varName&quot;) ;       // Get a result variable by name.
       Resource r = soln.getResource(&quot;VarR&quot;) ; // Get a result variable - must be a resource
       Literal l = soln.getLiteral(&quot;VarL&quot;) ;   // Get a result variable - must be a literal
     }
   }
 </code></pre>
 <p>It is important to cleanly close the query execution when finished.
 System resources connected to persistent storage may need to be
 released.</p>
 <p>A <code>ResultSet</code> supports the Java iterator interface so the
 following is also a way to process the results if preferred:</p>
 <pre><code>    Iterator&lt;QuerySolution&gt; results = qexec.execSelect() ;
     for ( ; results.hasNext() ; )
     {
         QuerySolution soln = results.next() ;
     . . .
     }
 </code></pre>
 <p>The step of creating a query and then a query execution can be
 reduced to one step in some common cases:</p>
 <pre><code>  import org.apache.jena.query.* ;
   Model model = ... ;
   String queryString = &quot; .... &quot; ;
   try (QueryExecution qexec = QueryExecutionFactory.create(queryString, model)) {
     ResultSet results = qexec.execSelect() ;
     . . .
   }
 </code></pre>
 <h3 id="passing-a-result-set-out-of-the-processing-loop">Passing a result set out of the processing loop.</h3>
 <p>A <code>ResultSet</code> is an iterator and can be traversed only once.  What is more, much of query execution
 and result set processing is handled internally in a streaming fashion. The <code>ResultSet</code> returned
 by <code>execSelect</code> is not valid after the <code>QueryExecution</code> is closed,
 whether explicitly or by
 try-resources as the <code>QueryExecution</code> implements <code>AutoCloseable</code>.</p>
 <p>A result set may be materialized - this is then usable outside</p>
 <pre><code>  try (QueryExecution qexec = QueryExecutionFactory.create(queryString, model)) {
       ResultSet results = qexec.execSelect() ;
       results = ResultSetFactory.copyResults(results) ;
       return results ;    // Passes the result set out of the try-resources
   }
 </code></pre>
 <p>The result set from <code>ResultSetFactory.copyResults</code> is a <code>ResultSetRewindable</code> which has a
 <code>reset()</code> operation that positions the iterator at the start of the result again.</p>
 <p>This can also be used when the results are going to be used in a loop that modifies
 the data.  It is not possible to update the model or dataset while looping
 over the results of a <code>SELECT</code> query.</p>
 <p>The models returned by <code>execConstruct</code> and <code>execDescribe</code> are valid
 after the <code>QueryExecution</code> is closed.</p>
 <h3 id="example-formatting-a-result-set">Example: formatting a result set</h3>
 <p>Instead of a loop to deal with each row in the result set, the
 application can call an operation of the <code>ResultSetFormatter</code>. This
 is what the command line applications do.</p>
 <p>Example: processing results to produce a simple text presentation:</p>
 <pre><code>    ResultSetFormatter fmt = new ResultSetFormatter(results, query) ;
     fmt.printAll(System.out) ;
 </code></pre>
 <p>or simply:</p>
 <pre><code> ResultSetFormatter.out(System.out, results, query) ;
 </code></pre>
 <h3 id="example-processing-results">Example: Processing results</h3>
 <p>The results are objects from the Jena RDF API and API calls, which
 do not modify the model, can be mixed with query results
 processing:</p>
 <pre><code>  for ( ; results.hasNext() ; )
   {
       // Access variables: soln.get(&quot;x&quot;) ;
       RDFNode n = soln.get(&quot;x&quot;) ; // &quot;x&quot; is a variable in the query
       // If you need to test the thing returned
       if ( n.isLiteral() )
           ((Literal)n).getLexicalForm() ;
       if ( n.isResource() )
       {
          Resource r = (Resource)n ;
           if ( ! r.isAnon() )
           {
             ... r.getURI() ...
           }
       }
   }
 </code></pre>
 <p>Updates to the model must be carried out after the query execution
 has finished. Typically, this involves collecting results of
 interest in a local datastructure and looping over that structure
 after the query execution has finished and been closed.</p>
 <h2 id="construct-queries">CONSTRUCT Queries</h2>
 <p><code>CONSTRUCT</code> queries return a single RDF graph. As usual, the query
 execution should be closed after use.</p>
 <pre><code>Query query = QueryFactory.create(queryString) ;
 QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
 Model resultModel = qexec.execConstruct() ;
 qexec.close() ;
 </code></pre>
 <h2 id="describe-queries">DESCRIBE Queries</h2>
 <p><code>DESCRIBE</code> queries return a single RDF graph.
 <a href="extension.html#describeHandlers">Different handlers</a> for the
 <code>DESCRIBE</code> operation can be loaded by added by the application.</p>
 <pre><code>Query query = QueryFactory.create(queryString) ;
 QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
 Model resultModel = qexec.execDescribe() ;
 qexec.close() ;
 </code></pre>
 <h2 id="ask-queries">ASK Queries</h2>
 <p>The operation Query.execAsk() returns a boolean value indicating
 whether the query pattern matched the graph or dataset or not.</p>
 <pre><code>Query query = QueryFactory.create(queryString) ;
 QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
 boolean result = qexec.execAsk() ;
 qexec.close() ;
 </code></pre>
 <h2 id="formatting-xml-results">Formatting XML results</h2>
 <p>The <code>ResultSetFormatter</code> class has methods to write out the
 <a href="http://www.w3.org/TR/rdf-sparql-XMLres/">SPARQL Query Results XML Format</a>.
 See ResultSetFormatter.outputAsXML method.</p>
 <h2 id="datasets">Datasets</h2>
 <p>The examples above are all queries on a single model.  A SPARQL
 query is made on a dataset, which is a default graph and zero or
 more named graphs. Datasets can be constructed using the
 <code>DatasetFactory</code>:</p>
 <pre><code>String dftGraphURI = &quot;file:default-graph.ttl&quot; ;
 List namedGraphURIs = new ArrayList() ;
 namedGraphURIs.add(&quot;file:named-1.ttl&quot;) ;
 namedGraphURIs.add(&quot;file:named-2.ttl&quot;) ;

 Query query = QueryFactory.create(queryString) ;

 Dataset dataset = DatasetFactory.create(dftGraphURI, namedGraphURIs) ;
 try(QueryExecution qExec = QueryExecutionFactory.create(query, dataset)) {
     ...
 }
 </code></pre>
 <p>Already existing models can also be used:</p>
 <pre><code>Dataset dataset = DatasetFactory.create() ;
 dataset.setDefaultModel(model) ;
 dataset.addNamedModel(&quot;http://example/named-1&quot;, modelX) ;
 dataset.addNamedModel(&quot;http://example/named-2&quot;, modelY) ;
  try(QueryExecution qExec = QueryExecutionFactory.create(query, dataset)) {
     ...
 }
 </code></pre>
 <p><a href="index.html">ARQ documentation index</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>
	<!DOCTYPE html>
	<html lang="en">
	<head>


	<title>Apache Jena - ARQ - Application API</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/query/app_api.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><a href='/documentation/query'>QUERY</a></li>







	<li class="active">APP API</li>




	</ol>





	</div>
	<h1 class="title">ARQ - Application API</h1>

	<p>The application API is in the package <code>org.apache.jena.query</code>.</p>
	<p>Other packages contain various parts of the system (execution
	engine, parsers, testing etc). Most applications will only need to
	use the main package. Only applications wishing to programmatically
	build queries or modify the behaviour of the query engine need to
	use the others packages directly.</p>
	<h2 id="key-classes">Key Classes</h2>
	<p>The package <code>org.apache.jena.query</code> is the main application
	package.</p>
	<ul>
	<li><code>Query</code> - a class that represents the application query. It is
	a container for all the details of the query. Objects of class
	Query are normally created by calling one of the methods of
	<code>QueryFactory</code> methods which provide access to the various parsers.</li>
	<li><code>QueryExecution</code> - represents one execution of a query.</li>
	<li><code>QueryExecutionFactory</code> - a place to get <code>QueryExecution</code> instances.</li>
	<li><code>DatasetFactory</code> - a place to make datasets.</li>
	<li>For SELECT queries:
	<ul>
	<li><code>QuerySolution</code> - A single solution to the query.</li>
	<li><code>ResultSet</code> - All the QuerySolutions. An iterator.</li>
	<li><code>ResultSetFormatter</code> - turn a ResultSet into various forms;
	into json, text, or as plain XML.</li>
	</ul>
	</li>
	</ul>
	<h2 id="select-queries">SELECT queries</h2>
	<p>The basic steps in making a SELECT query are outlined in the
	example below. A query is created from a string using the
	<code>QueryFactory</code>. The query and model or RDF dataset to be queried
	are then passed to <code>QueryExecutionFactory</code> to produce an instance
	of a query execution. <code>QueryExecution</code> objects are <code>java.lang.AutoCloseable</code>
	and can be used in try-resource. Result are handled in a loop and finally the
	query execution is closed.</p>
	<pre><code> import org.apache.jena.query.* ;
	Model model = ... ;
	String queryString = " .... " ;
	Query query = QueryFactory.create(queryString) ;
	try (QueryExecution qexec = QueryExecutionFactory.create(query, model)) {
	ResultSet results = qexec.execSelect() ;
	for ( ; results.hasNext() ; )
	{
	QuerySolution soln = results.nextSolution() ;
	RDFNode x = soln.get("varName") ; // Get a result variable by name.
	Resource r = soln.getResource("VarR") ; // Get a result variable - must be a resource
	Literal l = soln.getLiteral("VarL") ; // Get a result variable - must be a literal
	}
	}
	</code></pre>
	<p>It is important to cleanly close the query execution when finished.
	System resources connected to persistent storage may need to be
	released.</p>
	<p>A <code>ResultSet</code> supports the Java iterator interface so the
	following is also a way to process the results if preferred:</p>
	<pre><code> Iterator<QuerySolution> results = qexec.execSelect() ;
	for ( ; results.hasNext() ; )
	{
	QuerySolution soln = results.next() ;
	. . .
	}
	</code></pre>
	<p>The step of creating a query and then a query execution can be
	reduced to one step in some common cases:</p>
	<pre><code> import org.apache.jena.query.* ;
	Model model = ... ;
	String queryString = " .... " ;
	try (QueryExecution qexec = QueryExecutionFactory.create(queryString, model)) {
	ResultSet results = qexec.execSelect() ;
	. . .
	}
	</code></pre>
	<h3 id="passing-a-result-set-out-of-the-processing-loop">Passing a result set out of the processing loop.</h3>
	<p>A <code>ResultSet</code> is an iterator and can be traversed only once. What is more, much of query execution
	and result set processing is handled internally in a streaming fashion. The <code>ResultSet</code> returned
	by <code>execSelect</code> is not valid after the <code>QueryExecution</code> is closed,
	whether explicitly or by
	try-resources as the <code>QueryExecution</code> implements <code>AutoCloseable</code>.</p>
	<p>A result set may be materialized - this is then usable outside</p>
	<pre><code> try (QueryExecution qexec = QueryExecutionFactory.create(queryString, model)) {
	ResultSet results = qexec.execSelect() ;
	results = ResultSetFactory.copyResults(results) ;
	return results ; // Passes the result set out of the try-resources
	}
	</code></pre>
	<p>The result set from <code>ResultSetFactory.copyResults</code> is a <code>ResultSetRewindable</code> which has a
	<code>reset()</code> operation that positions the iterator at the start of the result again.</p>
	<p>This can also be used when the results are going to be used in a loop that modifies
	the data. It is not possible to update the model or dataset while looping
	over the results of a <code>SELECT</code> query.</p>
	<p>The models returned by <code>execConstruct</code> and <code>execDescribe</code> are valid
	after the <code>QueryExecution</code> is closed.</p>
	<h3 id="example-formatting-a-result-set">Example: formatting a result set</h3>
	<p>Instead of a loop to deal with each row in the result set, the
	application can call an operation of the <code>ResultSetFormatter</code>. This
	is what the command line applications do.</p>
	<p>Example: processing results to produce a simple text presentation:</p>
	<pre><code> ResultSetFormatter fmt = new ResultSetFormatter(results, query) ;
	fmt.printAll(System.out) ;
	</code></pre>
	<p>or simply:</p>
	<pre><code> ResultSetFormatter.out(System.out, results, query) ;
	</code></pre>
	<h3 id="example-processing-results">Example: Processing results</h3>
	<p>The results are objects from the Jena RDF API and API calls, which
	do not modify the model, can be mixed with query results
	processing:</p>
	<pre><code> for ( ; results.hasNext() ; )
	{
	// Access variables: soln.get("x") ;
	RDFNode n = soln.get("x") ; // "x" is a variable in the query
	// If you need to test the thing returned
	if ( n.isLiteral() )
	((Literal)n).getLexicalForm() ;
	if ( n.isResource() )
	{
	Resource r = (Resource)n ;
	if ( ! r.isAnon() )
	{
	... r.getURI() ...
	}
	}
	}
	</code></pre>
	<p>Updates to the model must be carried out after the query execution
	has finished. Typically, this involves collecting results of
	interest in a local datastructure and looping over that structure
	after the query execution has finished and been closed.</p>
	<h2 id="construct-queries">CONSTRUCT Queries</h2>
	<p><code>CONSTRUCT</code> queries return a single RDF graph. As usual, the query
	execution should be closed after use.</p>
	<pre><code>Query query = QueryFactory.create(queryString) ;
	QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
	Model resultModel = qexec.execConstruct() ;
	qexec.close() ;
	</code></pre>
	<h2 id="describe-queries">DESCRIBE Queries</h2>
	<p><code>DESCRIBE</code> queries return a single RDF graph.
	<a href="extension.html#describeHandlers">Different handlers</a> for the
	<code>DESCRIBE</code> operation can be loaded by added by the application.</p>
	<pre><code>Query query = QueryFactory.create(queryString) ;
	QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
	Model resultModel = qexec.execDescribe() ;
	qexec.close() ;
	</code></pre>
	<h2 id="ask-queries">ASK Queries</h2>
	<p>The operation Query.execAsk() returns a boolean value indicating
	whether the query pattern matched the graph or dataset or not.</p>
	<pre><code>Query query = QueryFactory.create(queryString) ;
	QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
	boolean result = qexec.execAsk() ;
	qexec.close() ;
	</code></pre>
	<h2 id="formatting-xml-results">Formatting XML results</h2>
	<p>The <code>ResultSetFormatter</code> class has methods to write out the
	<a href="http://www.w3.org/TR/rdf-sparql-XMLres/">SPARQL Query Results XML Format</a>.
	See ResultSetFormatter.outputAsXML method.</p>
	<h2 id="datasets">Datasets</h2>
	<p>The examples above are all queries on a single model. A SPARQL
	query is made on a dataset, which is a default graph and zero or
	more named graphs. Datasets can be constructed using the
	<code>DatasetFactory</code>:</p>
	<pre><code>String dftGraphURI = "file:default-graph.ttl" ;
	List namedGraphURIs = new ArrayList() ;
	namedGraphURIs.add("file:named-1.ttl") ;
	namedGraphURIs.add("file:named-2.ttl") ;

	Query query = QueryFactory.create(queryString) ;

	Dataset dataset = DatasetFactory.create(dftGraphURI, namedGraphURIs) ;
	try(QueryExecution qExec = QueryExecutionFactory.create(query, dataset)) {
	...
	}
	</code></pre>
	<p>Already existing models can also be used:</p>
	<pre><code>Dataset dataset = DatasetFactory.create() ;
	dataset.setDefaultModel(model) ;
	dataset.addNamedModel("http://example/named-1", modelX) ;
	dataset.addNamedModel("http://example/named-2", modelY) ;
	try(QueryExecution qExec = QueryExecutionFactory.create(query, dataset)) {
	...
	}
	</code></pre>
	<p><a href="index.html">ARQ documentation index</a></p>


	</div>
	</div>

	</div>

	<footer class="footer">
	<div class="container" style="font-size:80%" >
	<p>
	Copyright © 2011–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>