% This LaTeX document was generated using the LaTeX backend of PlDoc, % The SWI-Prolog documentation system The \file{library(semweb/rdf11)} provides a new interface to the SWI-Prolog RDF database based on the RDF 1.1 specification. \subsubsection{Query the RDF database} \label{sec:rdf11-query} \begin{description} \predicate[nondet]{rdf}{3}{?S, ?P, ?O} \nodescription \predicate[nondet]{rdf}{4}{?S, ?P, ?O, ?G} True if an RDF triple $<$\arg{S},\arg{P},\arg{O}$>$ exists, optionally in the graph \arg{G}. The object \arg{O} is either a resource (atom) or one of the terms listed below. The described types apply for the case where \arg{O} is unbound. If \arg{O} is instantiated it is converted according to the rules described with \predref{rdf_assert}{3}. Triples consist of the following three terms: \begin{itemize} \item Blank nodes are encoded by atoms that start with `_:`. \item IRIs appear in two notations: \begin{itemize} \item Full IRIs are encoded by atoms that do not start with `_:`. Specifically, an IRI term is not required to follow the IRI standard grammar. \item Abbreviated IRI notation that allows IRI prefix aliases that are registered by rdf_register_prefix/[2,3] to be used. Their notation is \verb$Alias:Local$, where Alias and Local are atoms. Each abbreviated IRI is expanded by the system to a full IRI. \end{itemize} \item Literals appear in two notations: \begin{description} \infixtermitem{@}{\arg{String}}{\arg{Lang}} A language-tagged string, where \arg{String} is a Prolog string and \arg{Lang} is an atom. \infixtermitem{\Shat{}\Shat{}}{\arg{Value}}{\arg{Type}} A type qualified literal. For unknown types, \arg{Value} is a Prolog string. If type is known, the Prolog representations from the table below are used. \begin{quote} \begin{tabulary}{0.9\textwidth}{|L|L|} \hline \textbf{\textbf{Datatype IRI}} & \textbf{\textbf{Prolog term}} \\ xsd:float & float \\ xsd:double & float \\ xsd:decimal & float (1) \\ xsd:integer & integer \\ XSD integer sub-types & integer \\ xsd:boolean & \const{true} or \const{false} \\ xsd:date & \verb$date(Y,M,D)$ \\ xsd:dateTime & \verb$date_time(Y,M,D,HH,MM,SS)$ (2,3) \\ xsd:gDay & integer \\ xsd:gMonth & integer \\ xsd:gMonthDay & \verb$month_day(M,D)$ \\ xsd:gYear & integer \\ xsd:gYearMonth & \verb$year_month(Y,M)$ \\ xsd:time & \verb$time(HH,MM,SS)$ (2) \\ \hline \end{tabulary} \end{quote} \end{description} \end{itemize} Notes: (1) The current implementation of \verb$xsd:decimal$ values as floats is formally incorrect. Future versions of SWI-Prolog may introduce decimal as a subtype of rational. (2) \arg{SS} fields denote the number of seconds. This can either be an integer or a float. (3) The \verb$date_time$ structure can have a 7th field that denotes the timezone offset \textbf{in seconds} as an integer. In addition, a \textit{ground} object value is translated into a properly typed RDF literal using \predref{rdf_canonical_literal}{2}. There is a fine distinction in how duplicate statements are handled in rdf/[3,4]: backtracking over \predref{rdf}{3} will never return duplicate triples that appear in multiple graphs. \predref{rdf}{4} will return such duplicate triples, because their graph term differs. \begin{arguments} \arg{S} & is the subject term. It is either a blank node or IRI. \\ \arg{P} & is the predicate term. It is always an IRI. \\ \arg{O} & is the object term. It is either a literal, a blank node or IRI (except for \const{true} and \const{false} that denote the values of datatype XSD boolean). \\ \arg{G} & is the graph term. It is always an IRI. \\ \end{arguments} \begin{tags} \mtag{See also}- \href{http://www.w3.org/TR/sparql11-query/\#sparqlTriplePatterns}{Triple pattern querying} \\- \predref{xsd_number_string}{2} and \predref{xsd_time_string}{3} are used to convert between lexical representations and Prolog terms. \end{tags} \predicate[nondet]{rdf_has}{3}{?S, +P, ?O} \nodescription \predicate[nondet]{rdf_has}{4}{?S, +P, ?O, -RealP} Similar to \predref{rdf}{3} and \predref{rdf}{4}, but \arg{P} matches all predicates that are defined as an rdfs:subPropertyOf of \arg{P}. This predicate also recognises the predicate properties \verb$inverse_of$ and \const{symmetric}. See \predref{rdf_set_predicate}{2}. \predicate[nondet]{rdf_reachable}{3}{?S, +P, ?O} \nodescription \predicate[nondet]{rdf_reachable}{5}{?S, +P, ?O, +MaxD, -D} True when \arg{O} can be reached from \arg{S} using the transitive closure of \arg{P}. The predicate uses (the internals of) \predref{rdf_has}{3} and thus matches both rdfs:subPropertyOf and the \verb$inverse_of$ and \const{symmetric} predicate properties. The version \predref{rdf_reachable}{5} maximizes the steps considered and returns the number of steps taken. If both \arg{S} and \arg{O} are given, these predicates are \const{semidet}. The number of steps \arg{D} is minimal because the implementation uses \textit{breadth first} search. \end{description} \paragraph{Constraints on literal values} \begin{description} \predicate[semidet]{\Scurl}{1}{+Where} \nodescription \predicate[semidet]{rdf_where}{1}{+Where} Formulate constraints on RDF terms, notably literals. These are intended to be used as illustrated below. RDF constraints are pure: they may be placed before, after or inside a graph pattern and, provided the code contains no \textit{commit} operations (!, \Sifthen{}), the semantics of the goal remains the same. Preferably, constraints are placed \textit{before} the graph pattern as they often help the RDF database to exploit its literal indexes. In the example below, the database can choose between using the subject and/or predicate hash or the ordered literal table. \begin{code} { Date >= "2000-01-01"^^xsd:date }, rdf(S, P, Date) \end{code} The following constraints are currently defined: \begin{description} \infixtermitem{\Scomma}{\term{\Sgt}{}}{\infixterm{\Scomma}{\term{\Sge}{}}{\infixterm{\Scomma}{\term{\Sequal}{}}{\infixterm{\Scomma}{\term{\Sle}{}}{\term{\Slt}{}}}}} The comparison operators are defined between numbers (of any recognised type), typed literals of the same type and langStrings of the same language. \termitem{prefix}{String, Pattern} \termitem{substring}{String, Pattern} \termitem{word}{String, Pattern} \termitem{like}{String, Pattern} \termitem{icase}{String, Pattern} Text matching operators that act on both typed literals and langStrings. \termitem{lang_matches}{Term, Pattern} Demands a full RDF term (Text@Lang) or a plain \arg{Lang} term to match the language pattern \arg{Pattern}. \end{description} The predicates \predref{rdf_where}{1} and \{\}/1 are identical. The \predref{rdf_where}{1} variant is provided to avoid ambiguity in applications where \{\}/1 is used for other purposes. Note that it is also possible to write \verb$rdf11:{...}$. \end{description} \subsubsection{Enumerating and testing objects} \label{sec:rdf11-enum}\paragraph{Enumerating objects by role}\label{sec:rdf11-enum-role} \begin{description} \predicate[nondet]{rdf_subject}{1}{?S} True when \arg{S} is a currently known \textit{subject}, i.e. it appears in the subject position of some visible triple. The predicate is \textit{semidet} if \arg{S} is ground. \predicate[nondet]{rdf_predicate}{1}{?P} True when \arg{P} is a currently known predicate, i.e. it appears in the predicate position of some visible triple. The predicate is \textit{semidet} if \arg{P} is ground. \predicate[nondet]{rdf_object}{1}{?O} True when \arg{O} is a currently known object, i.e. it appears in the object position of some visible triple. If Term is ground, it is pre-processed as the object argument of \predref{rdf_assert}{3} and the predicate is \textit{semidet}. \predicate[nondet]{rdf_node}{1}{?T} True when \arg{T} appears in the subject or object position of a known triple, i.e., is a node in the RDF graph. \predicate[nondet]{rdf_graph}{1}{?Graph} True when \arg{Graph} is an existing graph. \end{description} \paragraph{Enumerating objects by type}\label{sec:rdf11-enum-type} \begin{description} \predicate[nondet]{rdf_literal}{1}{?Term} True if \arg{Term} is a known literal. If \arg{Term} is ground, it is pre-processed as the object argument of \predref{rdf_assert}{3} and the predicate is \textit{semidet}. \predicate[nondet]{rdf_bnode}{1}{?BNode} True if \arg{BNode} is a currently known blank node. The predicate is \textit{semidet} if \arg{BNode} is ground. \predicate[nondet]{rdf_iri}{1}{?IRI} True if \arg{IRI} is a current \arg{IRI}. The predicate is \textit{semidet} if \arg{IRI} is ground. \predicate[nondet]{rdf_name}{1}{?Name} True if \arg{Name} is a current IRI or literal. The predicate is \textit{semidet} if \arg{Name} is ground. \predicate[nondet]{rdf_term}{1}{?Term} True if \arg{Term} appears in the RDF database. \arg{Term} is either an IRI, literal or blank node and may appear in any position of any triple. If \arg{Term} is ground, it is pre-processed as the object argument of \predref{rdf_assert}{3} and the predicate is \textit{semidet}. \end{description} \paragraph{Testing objects types}\label{sec:rdf11-type-test} \begin{description} \predicate[semidet]{rdf_is_iri}{1}{@IRI} True if \arg{IRI} is an RDF \arg{IRI} term. For performance reasons, this does not check for compliance to the syntax defined in \href{http://www.ietf.org/rfc/rfc3987.txt}{RFC 3987}. This checks whether the term is (1) an atom and (2) not a blank node identifier. Success of this goal does not imply that the \arg{IRI} is present in the database (see \predref{rdf_iri}{1} for that). \predicate[semidet]{rdf_is_bnode}{1}{@Term} True if \arg{Term} is an RDF blank node identifier. A blank node is represented by an atom that starts with \verb$_:$. Success of this goal does not imply that the blank node is present in the database (see \predref{rdf_bnode}{1} for that). For backwards compatibility, atoms that are represented with an atom that starts with \verb$__$ are also considered to be a blank node. \predicate[semidet]{rdf_is_literal}{1}{@Term} True if \arg{Term} is an RDF literal term. An RDF literal term is of the form \verb$String@LanguageTag$ or \verb$Value^^Datatype$. Success of this goal does not imply that the literal is well-formed or that it is present in the database (see \predref{rdf_literal}{1} for that). \predicate[semidet]{rdf_is_name}{1}{@Term} True if \arg{Term} is an RDF Name, i.e., an IRI or literal. Success of this goal does not imply that the name is well-formed or that it is present in the database (see \predref{rdf_name}{1} for that). \predicate[semidet]{rdf_is_object}{1}{@Term} True if \arg{Term} can appear in the object position of a triple. Success of this goal does not imply that the object term in well-formed or that it is present in the database (see \predref{rdf_object}{1} for that). Since any RDF term can appear in the object position, this is equaivalent to \predref{rdf_is_term}{1}. \predicate[semidet]{rdf_is_predicate}{1}{@Term} True if \arg{Term} can appear in the predicate position of a triple. Success of this goal does not imply that the predicate term is present in the database (see \predref{rdf_predicate}{1} for that). Since only IRIs can appear in the predicate position, this is equivalent to \predref{rdf_is_iri}{1}. \predicate[semidet]{rdf_is_subject}{1}{@Term} True if \arg{Term} can appear in the subject position of a triple. Only blank nodes and IRIs can appear in the subject position. Success of this goal does not imply that the subject term is present in the database (see \predref{rdf_subject}{1} for that). Since blank nodes are represented by atoms that start with `_:` and an IRIs are atoms as well, this is equivalent to \verb$atom(Term)$. \predicate[semidet]{rdf_is_term}{1}{@Term} True if \arg{Term} can be used as an RDF term, i.e., if \arg{Term} is either an IRI, a blank node or an RDF literal. Success of this goal does not imply that the RDF term is present in the database (see \predref{rdf_term}{1} for that). \end{description} \subsubsection{RDF literals} \label{sec:rdf11-literal} \begin{description} \predicate[det]{rdf_canonical_literal}{2}{++In, -Literal} Transform a relaxed literal specification as allowed for \predref{rdf_assert}{3} into its canonical form. The following Prolog terms are translated: \begin{quote} \begin{tabulary}{0.9\textwidth}{|l|l|} \hline \textbf{\textbf{Prolog Term}} & \textbf{\textbf{Datatype IRI}} \\ float & xsd:double \\ integer & xsd:integer \\ string & xsd:string \\ \const{true} or \const{false} & xsd:boolean \\ \verb$date(Y,M,D)$ & xsd:date \\ \verb$date_time(Y,M,D,HH,MM,SS)$ & xsd:dateTime \\ \verb$date_time(Y,M,D,HH,MM,SS,TZ)$ & xsd:dateTime \\ \verb$month_day(M,D)$ & xsd:gMonthDay \\ \verb$year_month(Y,M)$ & xsd:gYearMonth \\ \verb$time(HH,MM,SS)$ & xsd:time \\ \hline \end{tabulary} \end{quote} For example: \begin{code} ?- rdf_canonical_literal(42, X). X = 42^^'http://www.w3.org/2001/XMLSchema#integer'. \end{code} \predicate[det]{rdf_lexical_form}{2}{++Literal, -Lexical:compound} True when \arg{Lexical} is the lexical form for the literal \arg{Literal}. \arg{Lexical} is of one of the forms below. The ntriples serialization is obtained by transforming String into a proper ntriples string using double quotes and escaping where needed and turning Type into a proper IRI reference. \begin{shortlist} \item String\Shat{}\Shat{}Type \item String@Lang \end{shortlist} \predicate[det]{rdf_compare}{3}{-Diff, +Left, +Right} True if the RDF terms \arg{Left} and \arg{Right} are ordered according to the comparison operator \arg{Diff}. The ordering is defines as: \begin{itemize} \item Literal $<$ BNode $<$ IRI \item For literals \begin{itemize} \item Numeric $<$ non-numeric \item Numeric literals are ordered by value. If both are equal, floats are ordered before integers. \item Other data types are ordered lexicographically. \end{itemize} \item BNodes and IRIs are ordered lexicographically. \end{itemize} Note that this ordering is a complete ordering of RDF terms that is consistent with the partial ordering defined by SPARQL. \begin{arguments} \arg{Diff} & is one of \verb$<$, \verb$=$ or \verb$>$ \\ \end{arguments} \end{description} \subsubsection{Accessing RDF graphs} \label{sec:rdf11-graph} \begin{description} \predicate[det]{rdf_default_graph}{1}{-Graph} \nodescription \predicate[det]{rdf_default_graph}{2}{-Old, +New} Query/set the notion of the default graph. The notion of the default graph is local to a thread. Threads created inherit the default graph from their creator. See \predref{set_prolog_flag}{2}. \end{description} \subsubsection{Modifying the RDF store} \label{sec:rdf11-modify} \begin{description} \predicate[det]{rdf_assert}{3}{+S, +P, +O} \nodescription \predicate[det]{rdf_assert}{4}{+S, +P, +O, +G} Assert a new triple. If \arg{O} is a literal, certain Prolog terms are translated to typed RDF literals. These conversions are described with \predref{rdf_canonical_literal}{2}. If a type is provided using Value\Shat{}\Shat{}Type syntax, additional conversions are performed. All types accept either an atom or Prolog string holding a valid RDF lexical value for the type and xsd:float and xsd:double accept a Prolog integer. \predicate[nondet]{rdf_retractall}{3}{?S, ?P, ?O} \nodescription \predicate[nondet]{rdf_retractall}{4}{?S, ?P, ?O, ?G} Remove all matching triples from the database. Matching is performed using the same rules as \predref{rdf}{3}. The call does not instantiate any of its arguments. \predicate{rdf_create_bnode}{1}{--BNode} Create a new \arg{BNode}. A blank node is an atom starting with \verb$_:$. Blank nodes generated by this predicate are of the form \verb$_:genid$ followed by a unique integer. \end{description} \subsubsection{Accessing RDF collections} \label{sec:rdf11-collections} The following predicates are utilities to access RDF 1.1 \textit{collections}. A collection is a linked list created from \verb$rdf:first$ and \verb$rdf:next$ triples, ending in \verb$rdf:nil$. \begin{description} \predicate[det]{rdf_last}{2}{+RDFList, -Last} True when \arg{Last} is the last element of \arg{RDFList}. Note that if the last cell has multiple rdf:first triples, this predicate becomes nondet. \predicate[semidet]{rdf_list}{1}{?RDFTerm} True if \arg{RDFTerm} is a proper RDF list. This implies that every node in the list has an \verb$rdf:first$ and \verb$rdf:rest$ property and the list ends in \verb$rdf:nil$. If \arg{RDFTerm} is unbound, \arg{RDFTerm} is bound to each \textit{maximal} RDF list. An RDF list is \textit{maximal} if there is no triple \verb$rdf(_, rdf:rest, RDFList)$. \predicate[det]{rdf_list}{2}{+RDFList, -PrologList} True when \arg{PrologList} represents the rdf:first objects for all cells in \arg{RDFList}. Note that this can be non-deterministic if cells have multiple rdf:first or rdf:rest triples. \predicate[nondet]{rdf_length}{2}{+RDFList, -Length:nonneg} True when \arg{Length} is the number of cells in \arg{RDFList}. Note that a list cell may have multiple rdf:rest triples, which makes this predicate non-deterministic. This predicate does not check whether the list cells have associated values (rdf:first). The list must end in rdf:nil. \predicate[nondet]{rdf_member}{2}{?Member, +RDFList} True when \arg{Member} is a member of \arg{RDFList} \predicate[nondet]{rdf_nth0}{3}{?Index, +RDFList, ?X} \nodescription \predicate[nondet]{rdf_nth1}{3}{?Index, +RDFList, ?X} True when \arg{X} is the \arg{Index}-th element (0-based or 1-based) of \arg{RDFList}. This predicate is deterministic if \arg{Index} is given and the list has no multiple rdf:first or rdf:rest values. \predicate[det]{rdf_assert_list}{2}{+PrologList, ?RDFList} \nodescription \predicate[det]{rdf_assert_list}{3}{+PrologList, ?RDFList, +Graph} Create an RDF list from the given Prolog List. \arg{PrologList} must be a proper Prolog list and all members of the list must be acceptable as object for \predref{rdf_assert}{3}. If \arg{RDFList} is unbound and \arg{PrologList} is not empty, \predref{rdf_create_bnode}{1} is used to create \arg{RDFList}. \predicate[det]{rdf_retract_list}{1}{+RDFList} Retract the rdf:first, rdf:rest and rdf:type=rdf:'List' triples from all nodes reachable through rdf:rest. Note that other triples that exist on the nodes are left untouched. \end{description}