rdf_db.pl -- Core RDF database

The file library(semweb/rdf_db) provides the core of the SWI-Prolog RDF store.

deprecated: - New applications should use library(semweb/rdf11), which provides a much more intuitive API to the RDF store, notably for handling literals. The library(semweb/rdf11) runs currently on top of this library and both can run side-by-side in the same application. Terms retrieved from the database however have a different shape and can not be exchanged without precautions.

rdf_current_prefix(:Alias, ?URI) is nondet

Query predefined prefixes and prefixes defined with rdf_register_prefix/2 and local prefixes defined with rdf_prefix/2. If Alias is unbound and one URI is the prefix of another, the longest is returned first. This allows turning a resource into a prefix/local couple using the simple enumeration below. See rdf_global_id/2.

rdf_current_prefix(Prefix, Expansion),
atom_concat(Expansion, Local, URI),

rdf_prefix(:Alias, +URI) is det

Register a local prefix. This declaration takes precedence over globally defined prefixes using rdf_register_prefix/2,3. Module local prefixes are notably required to deal with SWISH, where users need to be able to have independent namespace declarations.

ns(?Alias, ?URI) is nondet[multifile]

Dynamic and multifile predicate that maintains the registered namespace aliases.

deprecated: - New code must modify the namespace table using rdf_register_ns/3 and query using rdf_current_ns/2.

rdf_register_prefix(+Prefix, +URI) is det

rdf_register_prefix(+Prefix, +URI, +Options) is det

force(Boolean): If true, Replace existing namespace alias. Please note that replacing a namespace is dangerous as namespaces affect preprocessing. Make sure all code that depends on a namespace is compiled after changing the registration.
keep(Boolean): If true and Alias is already defined, keep the original binding for Prefix and succeed silently.

Without options, an attempt to redefine an alias raises a permission error.

Predefined prefixes are:

Alias	IRI prefix
dc	http://purl.org/dc/elements/1.1/
dcterms	http://purl.org/dc/terms/
eor	http://dublincore.org/2000/03/13/eor#
foaf	http://xmlns.com/foaf/0.1/
owl	http://www.w3.org/2002/07/owl#
rdf	http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs	http://www.w3.org/2000/01/rdf-schema#
serql	http://www.openrdf.org/schema/serql#
skos	http://www.w3.org/2004/02/skos/core#
void	http://rdfs.org/ns/void#
xsd	http://www.w3.org/2001/XMLSchema#

register_global_prefix(+Alias, +URI, +Options)[private]

rdf_current_ns(:Prefix, ?URI) is nondet

deprecated: - . Use rdf_current_prefix/2.

rdf_register_ns(:Prefix, ?URI) is det

rdf_register_ns(:Prefix, ?URI, +Options) is det

deprecated: - . Use rdf_register_prefix/2 or rdf_register_prefix/3.

register_file_ns(+Map:list(pair)) is det[private]

Register a namespace as encounted in the namespace list of an RDF document. We only register if both the abbreviation and URL are not already known. Is there a better way? This code could also do checks on the consistency of RDF and other well-known namespaces.

To be done: - Better error handling

rdf_global_id(?IRISpec, :IRI) is semidet

Convert between Prefix:Local and full IRI (an atom). If IRISpec is an atom, it is simply unified with IRI. This predicate fails silently if IRI is an RDF literal.

Note that this predicate is a meta-predicate on its output argument. This is necessary to get the module context while the first argument may be of the form (:)/2. The above mode description is correct, but should be interpreted as (?,?).

Errors: - existence_error(rdf_prefix, Prefix)
See also: - rdf_equal/2 provides a compile time alternative; - The rdf_meta/1 directive asks for compile time expansion of arguments.
bug: - Error handling is incomplete. In its current implementation the same code is used for compile-time expansion and to facilitate runtime conversion and checking. These use cases have different requirements.

rdf_global_object(+Object, :GlobalObject) is semidet

rdf_global_object(-Object, :GlobalObject) is semidet

Same as rdf_global_id/2, but intended for dealing with the object part of a triple, in particular the type for typed literals. Note that the predicate is a meta-predicate on the output argument. This is necessary to get the module context while the first argument may be of the form (:)/2.

Errors: - existence_error(rdf_prefix, Prefix)

rdf_global_term(+TermIn, :GlobalTerm) is det

Does rdf_global_id/2 on all terms NS:Local by recursively analysing the term. Note that the predicate is a meta-predicate on the output argument. This is necessary to get the module context while the first argument may be of the form (:)/2.

Terms of the form Prefix:Local that appear in TermIn for which Prefix is not defined are not replaced. Unlike rdf_global_id/2 and rdf_global_object/2, no error is raised.

rdf_global_graph(+TermIn, -GlobalTerm, +Module) is det[private]

Preforms rdf_global_id/2 on rdf/4, etc graph arguments

rdf_meta(+Heads)

This directive defines the argument types of the named predicates, which will force compile time namespace expansion for these predicates. Heads is a coma-separated list of callable terms. Defined argument properties are:

:: Argument is a goal. The goal is processed using expand_goal/2, recursively applying goal transformation on the argument.
+: The argument is instantiated at entry. Nothing is changed.
-: The argument is not instantiated at entry. Nothing is changed.
?: The argument is unbound or instantiated at entry. Nothing is changed.
@: The argument is not changed.
r: The argument must be a resource. If it is a term prefix:local it is translated.
o: The argument is an object or resource. See rdf_global_object/2.
t: The argument is a term that must be translated. Expansion will translate all occurences of prefix:local appearing anywhere in the term. See rdf_global_term/2.

As it is subject to term_expansion/2, the rdf_meta/1 declaration can only be used as a directive. The directive must be processed before the definition of the predicates as well as before compiling code that uses the rdf meta-predicates. The atom rdf_meta is declared as an operator exported from library(semweb/rdf_db). Files using rdf_meta/1 must explicitely load this library.

Beginning with SWI-Prolog 7.3.17, the low-level RDF interface (rdf/3, rdf_assert/3, etc.) perform runtime expansion of Prefix:Local terms. This eliminates the need for rdf_meta/1 for simple cases. However, runtime expansion comes at a significant overhead and having two representations for IRIs (a plain atom and a term Prefix:Local) implies that simple operations such as comparison of IRIs no longer map to native Prolog operations such as IRI1 == IRI2.

rdf_meta_specification(+General, +Module, -Spec) is semidet[private]

True when Spec is the RDF meta specification for Module:General.

Arguments:

General

- is the term Spec with all arguments replaced with variables.

mk_global(+Src, -Resource, +Module)[private]

Realised rdf_global_id(+, -), but adds compiletime checking, notably to see whether a namespace is not yet defined.

rdf_equal(?Resource1, ?Resource2)

Simple equality test to exploit goal-expansion

lang_equal(+Lang1, +Lang2) is semidet

True if two RFC language specifiers denote the same language

See also: - lang_matches/2.

lang_matches(+Lang, +Pattern) is semidet

True if Lang matches Pattern. This implements XML language matching conform RFC 4647. Both Lang and Pattern are dash-separated strings of identifiers or (for Pattern) the wildcart *. Identifiers are matched case-insensitive and a * matches any number of identifiers. A short pattern is the same as *.

rdf(?Subject, ?Predicate, ?Object) is nondet

Elementary query for triples. Subject and Predicate are atoms representing the fully qualified URL of the resource. Object is either an atom representing a resource or literal(Value) if the object is a literal value. If a value of the form NameSpaceID:LocalName is provided it is expanded to a ground atom using expand_goal/2. This implies you can use this construct in compiled code without paying a performance penalty. Literal values take one of the following forms:

Atom: If the value is a simple atom it is the textual representation of a string literal without explicit type or language qualifier.
lang(LangID, Atom): Atom represents the text of a string literal qualified with the given language.
type(TypeID, Value): Used for attributes qualified using the rdf:datatype TypeID. The Value is either the textual representation or a natural Prolog representation. See the option convert_typed_literal(:Convertor) of the parser. The storage layer provides efficient handling of atoms, integers (64-bit) and floats (native C-doubles). All other data is represented as a Prolog record.

For literal querying purposes, Object can be of the form literal(+Query, -Value), where Query is one of the terms below. If the Query takes a literal argument and the value has a numeric type numerical comparison is performed.

plain(+Text): Perform exact match and demand the language or type qualifiers to match. This query is fully indexed.
icase(+Text): Perform a full but case-insensitive match. This query is fully indexed.
exact(+Text): Same as icase(Text). Backward compatibility.
substring(+Text): Match any literal that contains Text as a case-insensitive substring. The query is not indexed on Object.
word(+Text): Match any literal that contains Text delimited by a non alpha-numeric character, the start or end of the string. The query is not indexed on Object.
prefix(+Text): Match any literal that starts with Text. This call is intended for completion. The query is indexed using the skip list of literals.
ge(+Literal): Match any literal that is equal or larger then Literal in the ordered set of literals.
gt(+Literal): Match any literal that is larger then Literal in the ordered set of literals.
eq(+Literal): Match any literal that is equal to Literal in the ordered set of literals.
le(+Literal): Match any literal that is equal or smaller then Literal in the ordered set of literals.
lt(+Literal): Match any literal that is smaller then Literal in the ordered set of literals.
between(+Literal1, +Literal2): Match any literal that is between Literal1 and Literal2 in the ordered set of literals. This may include both Literal1 and Literal2.
like(+Pattern): Match any literal that matches Pattern case insensitively, where the `*' character in Pattern matches zero or more characters.

Backtracking never returns duplicate triples. Duplicates can be retrieved using rdf/4. The predicate rdf/3 raises a type-error if called with improper arguments. If rdf/3 is called with a term literal(_) as Subject or Predicate object it fails silently. This allows for graph matching goals like rdf(S,P,O),rdf(O,P2,O2) to proceed without errors.

rdf(?Subject, ?Predicate, ?Object, ?Source) is nondet

As rdf/3 but in addition query the graph to which the triple belongs. Unlike rdf/3, this predicate does not remove duplicates from the result set.

Arguments:

Source

- is a term Graph:Line. If Source is instatiated, passing an atom is the same as passing Atom:_.

rdf_has(?Subject, +Predicate, ?Object) is nondet

Succeeds if the triple rdf(Subject, Predicate, Object) is true exploiting the rdfs:subPropertyOf predicate as well as inverse predicates declared using rdf_set_predicate/2 with the inverse_of property.

rdf_has(?Subject, +Predicate, ?Object, -RealPredicate) is nondet

Same as rdf_has/3, but RealPredicate is unified to the actual predicate that makes this relation true. RealPredicate must be Predicate or an rdfs:subPropertyOf Predicate. If an inverse match is found, RealPredicate is the term inverse_of(Pred).

rdf_reachable(?Subject, +Predicate, ?Object) is nondet

Is true if Object can be reached from Subject following the transitive predicate Predicate or a sub-property thereof, while repecting the symetric(true) or inverse_of(P2) properties.

If used with either Subject or Object unbound, it first returns the origin, followed by the reachable nodes in breath-first search-order. The implementation internally looks one solution ahead and succeeds deterministically on the last solution. This predicate never generates the same node twice and is robust against cycles in the transitive relation.

With all arguments instantiated, it succeeds deterministically if a path can be found from Subject to Object. Searching starts at Subject, assuming the branching factor is normally lower. A call with both Subject and Object unbound raises an instantiation error. The following example generates all subclasses of rdfs:Resource:

?- rdf_reachable(X, rdfs:subClassOf, rdfs:'Resource').
X = 'http://www.w3.org/2000/01/rdf-schema#Resource' ;
X = 'http://www.w3.org/2000/01/rdf-schema#Class' ;
X = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#Property' ;
...

rdf_reachable(?Subject, +Predicate, ?Object, +MaxD, -D) is nondet

Same as rdf_reachable/3, but in addition, MaxD limits the number of edges expanded and D is unified with the `distance' between Subject and Object. Distance 0 means Subject and Object are the same resource. MaxD can be the constant infinite to impose no distance-limit.

rdf_subject(?Resource) is nondet

True if Resource appears as a subject. This query respects the visibility rules implied by the logical update view.

See also: - rdf_resource/1.

rdf_resource(?Resource) is nondet

True when Resource is a resource used as a subject or object in a triple.

This predicate is primarily intended as a way to process all resources without processing resources twice. The user must be aware that some of the returned resources may not appear in any visible triple.

rdf_assert(+Subject, +Predicate, +Object) is det

Assert a new triple into the database. This is equivalent to rdf_assert/4 using Graph user. Subject and Predicate are resources. Object is either a resource or a term literal(Value). See rdf/3 for an explanation of Value for typed and language qualified literals. All arguments are subject to name-space expansion. Complete duplicates (including the same graph and `line' and with a compatible `lifespan') are not added to the database.

rdf_assert(+Subject, +Predicate, +Object, +Graph) is det

As rdf_assert/3, adding the predicate to the indicated named graph.

Arguments:

Graph

- is either the name of a graph (an atom) or a term Graph:Line, where Line is an integer that denotes a line number.

rdf_retractall(?Subject, ?Predicate, ?Object) is det

Remove all matching triples from the database. As rdf_retractall/4 using an unbound graph.

rdf_retractall(?Subject, ?Predicate, ?Object, ?Graph) is det

As rdf_retractall/3, also matching Graph. This is particulary useful to remove all triples coming from a loaded file. See also rdf_unload/1.

rdf_update(+Subject, +Predicate, +Object, +Action) is det

Replaces one of the three fields on the matching triples depending on Action:

subject(Resource): Changes the first field of the triple.
predicate(Resource): Changes the second field of the triple.
object(Object): Changes the last field of the triple to the given resource or literal(Value).
graph(Graph): Moves the triple from its current named graph to Graph.

rdf_update(+Subject, +Predicate, +Object, +Graph, +Action) is det

As rdf_update/4 but allows for specifying the graph.

rdf_member_property(?Prop, ?Index)

Deal with the rdf:_1, ... properties.

rdf_node(-Id)

Generate a unique blank node identifier for a subject.

deprecated: - New code should use rdf_bnode/1.

rdf_bnode(-Id)

Generate a unique anonymous identifier for a subject.

rdf_is_bnode(+Id)

Tests if a resource is a blank node (i.e. is an anonymous resource). A blank node is represented as an atom that starts with _:. For backward compatibility reason, __ is also considered to be a blank node.

See also: - rdf_bnode/1.

rdf_is_resource(@Term) is semidet

True if Term is an RDF resource. Note that this is merely a type-test; it does not mean this resource is involved in any triple. Blank nodes are also considered resources.

See also: - rdf_is_bnode/1

rdf_is_literal(@Term) is semidet

True if Term is an RDF literal object. Currently only checks for groundness and the literal functor.

rdf_current_literal(-Literal) is nondet

True when Literal is a currently known literal. Enumerates each unique literal exactly once. Note that it is possible that the literal only appears in already deleted triples. Deleted triples may be locked due to active queries, transactions or snapshots or may not yet be reclaimed by the garbage collector.

rdf_literal_value(+Literal, -Value) is semidet