% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(semweb/sparql_client): SPARQL client library}

\label{sec:sparqlclient}

This module provides a SPARQL client. For example:

\begin{code}
?- sparql_query('select * where { ?x rdfs:label "Amsterdam" }', Row,
                [ host('dbpedia.org'), path('/sparql/')]).

Row = row('http://www.ontologyportal.org/WordNet#WN30-108949737') ;
false.
\end{code}

Or, querying a local server using an \verb$ASK$ query:

\begin{code}
?- sparql_query('ask { owl:Class rdfs:label "Class" }', Row,
                [ host('localhost'), port(3020), path('/sparql/')]).
Row = true.
\end{code}

HTTPS servers are supported using the \verb$scheme(https)$ option:

\begin{code}
?- sparql_query('select * where { ?x rdfs:label "Amsterdam"@nl }',
                Row,
                [ scheme(https),
                  host('query.wikidata.org'),
                  path('/sparql')
                ]).
\end{code}

\vspace{0.7cm}

\begin{description}
    \predicate[nondet]{sparql_query}{3}{+Query, -Result, +Options}
Execute a SPARQL query on an HTTP SPARQL endpoint. \arg{Query} is an atom
that denotes the query. \arg{Result} is unified to a term \verb$rdf(S,P,O)$ for
\verb$CONSTRUCT$ and \verb$DESCRIBE$ queries, \verb$row(...)$ for \verb$SELECT$
queries and \const{true} or \const{false} for \verb$ASK$ queries. \arg{Options} are

Variables that are unbound in SPARQL (e.g., due to SPARQL optional
clauses), are bound in Prolog to the atom \verb|'$null$'|.

\begin{description}
    \termitem{endpoint}{+URL}
May be used as alternative to Scheme, Host, Port and Path
to specify the endpoint in a single option.
    \termitem{host}{+Host}
    \termitem{port}{+Port}
    \termitem{path}{+Path}
    \termitem{scheme}{+Scheme}
The above four options set the location of the server.
    \termitem{search}{+ListOfParams}
Provide additional query parameters, such as the graph.
    \termitem{variable_names}{-ListOfNames}
Unifies \arg{ListOfNames} with a list of atoms that describe the
names of the variables in a \verb$SELECT$ query.
\end{description}

Remaining options are passed to \predref{http_open}{3}. The defaults for Host,
Port and Path can be set using \predref{sparql_set_server}{1}. The initial
default for port is 80 and path is `/sparql/`.

For example, the ClioPatria server understands the parameter
\const{entailment}. The code below queries for all triples using
_rdfs_entailment.

\begin{code}
?- sparql_query('select * where { ?s ?p ?o }',
                Row,
                [ search([entailment=rdfs])
                ]).
\end{code}

Another useful option is the \verb$request_header$ which, for example,
may be used to trick force a server to reply using a particular
document format:

\begin{code}
?- sparql_query(
       'select * where { ?s ?p ?o }',
        Row,
        [ host('integbio.jp'),
          path('/rdf/sparql'),
          request_header('Accept' =
                         'application/sparql-results+xml')
        ]).
\end{code}

    \predicate{sparql_set_server}{1}{+OptionOrList}
Set sparql server default options. Provided defaults are:
host, port and repository. For example:

\begin{code}
    sparql_set_server([ host(localhost),
                        port(8080)
                        path(world)
                      ])
\end{code}

The default for port is 80 and path is \verb$/sparql/$.

    \predicate{sparql_read_xml_result}{2}{+Input, -Result}
Specs from \url{http://www.w3.org/TR/rdf-sparql-XMLres/}. The returned
\arg{Result} term is of the format:

\begin{description}
    \termitem{select}{VarNames, Rows}
Where \arg{VarNames} is a term \verb$v(Name, ...)$ and \arg{Rows} is a
list of \verb$row(....)$ containing the column values in the
same order as the variable names.
    \termitem{ask}{Bool}
Where \arg{Bool} is either \const{true} or \const{false}
\end{description}

    \predicate[det]{sparql_read_json_result}{2}{+Input, -Result}
The returned \arg{Result} term is of the format:

\begin{description}
    \termitem{select}{VarNames, Rows}
Where \arg{VarNames} is a term \verb$v(Name, ...)$ and \arg{Rows} is a
list of \verb$row(....)$ containing the column values in the
same order as the variable names.
    \termitem{ask}{Bool}
Where \arg{Bool} is either \const{true} or \const{false}
\end{description}

\begin{tags}
    \tag{See also}
\url{http://www.w3.org/TR/rdf-sparql-json-res/}
\end{tags}
\end{description}