Did you know ... Search Documentation:
rdf11.pl -- RDF 1.1 API
PublicShow source

This library provides a new API on top of library(semweb/rdf_db). The new API follows the RDF 1.1 terminology and notation as much as possible. It runs on top of the old API, which implies that applications can use the new API in one file and the other in another one. Once the new API is considered stable and robust the old API will be deprecated.

In a nutshell, the following issues are addressed:

  • Literals are now represented by Value^^Type or Text@Lang. Plain literals no longer exist. Value is a Prolog representation of the value for known types. In particular:
    • xsd:double, xsd:float and xsd:decimal are represented by a Prolog float
    • Integer types are represented by a Prolog integer
    • The date/time types are presented by Prolog terms
  • Literal matching and comparison operations are represented as Prolog constraints. This replaces the literal(+Search,-Value) construct used by library(semweb/rdf_db). For example, the following query returns literals with prefix "ams", exploiting the RDF literal index.
    { prefix(Name, "ams") },
    rdf(S,P,Name).
  • Graphs are always identified by the graph name only, i.e., the notation Graph:Line is no longer supported. If a graph name is an IRI then RDF prefix notation can now be used.
  • The enumeration and type-testing predicates are now more closely based on the RDF 1.1 specification and use consistent naming.
author
- Jan Wielemaker
- Wouter Beek
version
- 2016
See also
- https://github.com/SWI-Prolog/packages-semweb/wiki/Proposal-for-Semweb-library-redesign
Source rdf(?S, ?P, ?O) is nondet
Source rdf(?S, ?P, ?O, ?G) is nondet
True if an RDF triple <S,P,O> exists, optionally in the graph G. The object O is either a resource (atom) or one of the terms listed below. The described types apply for the case where O is unbound. If O is instantiated it is converted according to the rules described with rdf_assert/3.

Triples consist of the following three terms:

  • Blank nodes are encoded by atoms that start with `_:`.
  • IRIs appear in two notations:
    • Full IRIs are encoded by atoms that do not start with `_:`. Specifically, an IRI term is not required to follow the IRI standard grammar.
    • Abbreviated IRI notation that allows IRI prefix aliases that are registered by rdf_register_prefix/[2,3] to be used. Their notation is Alias:Local, where Alias and Local are atoms. Each abbreviated IRI is expanded by the system to a full IRI.
  • Literals appear in two notations:
    • String@Lang A language-tagged string, where String is a Prolog string and Lang is an atom.
    • Value^^Type A type qualified literal. For unknown types, Value is a Prolog string. If type is known, the Prolog representations from the table below are used.
      Datatype IRIProlog term
      xsd:floatfloat
      xsd:doublefloat
      xsd:decimalfloat (1)
      xsd:integerinteger
      XSD integer sub-typesinteger
      xsd:booleantrue or false
      xsd:datedate(Y,M,D)
      xsd:dateTimedate_time(Y,M,D,HH,MM,SS) (2,3)
      xsd:gDayinteger
      xsd:gMonthinteger
      xsd:gMonthDaymonth_day(M,D)
      xsd:gYearinteger
      xsd:gYearMonthyear_month(Y,M)
      xsd:timetime(HH,MM,SS) (2)

Notes:

(1) The current implementation of xsd:decimal values as floats is formally incorrect. Future versions of SWI-Prolog may introduce decimal as a subtype of rational.

(2) SS fields denote the number of seconds. This can either be an integer or a float.

(3) The date_time structure can have a 7th field that denotes the timezone offset in seconds as an integer.

In addition, a ground object value is translated into a properly typed RDF literal using rdf_canonical_literal/2.

There is a fine distinction in how duplicate statements are handled in rdf/[3,4]: backtracking over rdf/3 will never return duplicate triples that appear in multiple graphs. rdf/4 will return such duplicate triples, because their graph term differs.

Arguments:
S- is the subject term. It is either a blank node or IRI.
P- is the predicate term. It is always an IRI.
O- is the object term. It is either a literal, a blank node or IRI (except for true and false that denote the values of datatype XSD boolean).
G- is the graph term. It is always an IRI.
See also
- Triple pattern querying
- xsd_number_string/2 and xsd_time_string/3 are used to convert between lexical representations and Prolog terms.
Source rdf_has(?S, ?P, ?O) is nondet
Source rdf_has(?S, ?P, ?O, -RealP) is nondet
Similar to rdf/3 and rdf/4, but P matches all predicates that are defined as an rdfs:subPropertyOf of P. This predicate also recognises the predicate properties inverse_of and symmetric. See rdf_set_predicate/2.
Source rdf_update(+S, +P, +O, ++Action) is det
Source rdf_update(+S, +P, +O, +G, ++Action) is det
Replaces one of the three (four) 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. This only works with rdf_update/5 and throws an error when used with rdf_update/4.

The argument matching Action must be ground. If this argument is equivalent to the current value, no action is performed. Otherwise, the requested action is performed on all matching triples. For example, all resources typed rdfs:Class can be changed to owl:Class using

?- rdf_update(_, rdf:type, rdfs:'Class',
              object(owl:'Class')).
Errors
- instantiation_error if Action or the matching argument is not ground.
- domain_error(rdf_update_action, Action) if Action is not one of the above terms.
Source rdf_reachable(?S, +P, ?O) is nondet
Source rdf_reachable(?S, +P, ?O, +MaxD, -D) is nondet
True when O can be reached from S using the transitive closure of P. The predicate uses (the internals of) rdf_has/3 and thus matches both rdfs:subPropertyOf and the inverse_of and symmetric predicate properties. The version rdf_reachable/5 maximizes the steps considered and returns the number of steps taken.

If both S and O are given, these predicates are semidet. The number of steps D is minimal because the implementation uses breadth first search.

Source rdf_assert(+S, +P, +O) is det
Source rdf_assert(+S, +P, +O, +G) is det
Assert a new triple. If O is a literal, certain Prolog terms are translated to typed RDF literals. These conversions are described with rdf_canonical_literal/2.

If a type is provided using Value^^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.

Source rdf_retractall(?S, ?P, ?O) is nondet
Source rdf_retractall(?S, ?P, ?O, ?G) is nondet
Remove all matching triples from the database. Matching is performed using the same rules as rdf/3. The call does not instantiate any of its arguments.
Source rdf_compare(-Diff, +Left, +Right) is det
True if the RDF terms Left and Right are ordered according to the comparison operator Diff. The ordering is defines as:
  • Literal < BNode < IRI
  • For literals
    • Numeric < non-numeric
    • Numeric literals are ordered by value. If both are equal, floats are ordered before integers.
    • Other data types are ordered lexicographically.
  • BNodes and IRIs are ordered lexicographically.

Note that this ordering is a complete ordering of RDF terms that is consistent with the partial ordering defined by SPARQL.

Arguments:
Diff- is one of <, = or >
Source {}(+Where) is semidet
Source rdf_where(+Where) is semidet
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 commit operations (!, ->), the semantics of the goal remains the same. Preferably, constraints are placed 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.
    { Date >= "2000-01-01"^^xsd:date },
    rdf(S, P, Date)

The following constraints are currently defined:

>,>=,==,=<,<
The comparison operators are defined between numbers (of any recognised type), typed literals of the same type and langStrings of the same language.
prefix(String, Pattern)
substring(String, Pattern)
word(String, Pattern)
like(String, Pattern)
icase(String, Pattern)
Text matching operators that act on both typed literals and langStrings.
lang_matches(Term, Pattern)
Demands a full RDF term (Text@Lang) or a plain Lang term to match the language pattern Pattern.

The predicates rdf_where/1 and {}/1 are identical. The 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 rdf11:{...}.

Source rdf_default_graph(-Graph) is det
Source rdf_default_graph(-Old, +New) is det
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 set_prolog_flag/2.
Source rdf_canonical_literal(++In, -Literal) is det
Transform a relaxed literal specification as allowed for rdf_assert/3 into its canonical form. The following Prolog terms are translated:
Prolog TermDatatype IRI
floatxsd:double
integerxsd:integer
stringxsd:string
true or falsexsd:boolean
date(Y,M,D)xsd:date
date_time(Y,M,D,HH,MM,SS)xsd:dateTime
date_time(Y,M,D,HH,MM,SS,TZ)xsd:dateTime
month_day(M,D)xsd:gMonthDay
year_month(Y,M)xsd:gYearMonth
time(HH,MM,SS)xsd:time

For example:

?- rdf_canonical_literal(42, X).
X = 42^^'http://www.w3.org/2001/XMLSchema#integer'.
Source rdf_lexical_form(++Literal, -Lexical:compound) is det
True when Lexical is the lexical form for the literal Literal. 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.
  • String^^Type
  • String@Lang
Source invalid_lexical_form_hook(+Type, +Lexical, -Prolog)[multifile]
This hook is called if translation of the lexical form to the Prolog representation fails due to a syntax error. By default it is not defined, causing such invalid triples to be silently ignored.
Source rdf_term(?Term) is nondet
True if Term appears in the RDF database. Term is either an IRI, literal or blank node and may appear in any position of any triple. If Term is ground, it is pre-processed as the object argument of rdf_assert/3 and the predicate is semidet.
Source rdf_literal(?Term) is nondet
True if Term is a known literal. If Term is ground, it is pre-processed as the object argument of rdf_assert/3 and the predicate is semidet.
Source rdf_bnode(?BNode) is nondet
True if BNode is a currently known blank node. The predicate is semidet if BNode is ground.
Source rdf_iri(?IRI) is nondet
True if IRI is a current IRI. The predicate is semidet if IRI is ground.
Source rdf_name(?Name) is nondet
True if Name is a current IRI or literal. The predicate is semidet if Name is ground.
 rdf_subject(?S) is nondet
True when S is a currently known subject, i.e. it appears in the subject position of some visible triple. The predicate is semidet if S is ground.
Source rdf_predicate(?P) is nondet
True when P is a currently known predicate, i.e. it appears in the predicate position of some visible triple. The predicate is semidet if P is ground.
Source rdf_object(?O) is nondet
True when 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 rdf_assert/3 and the predicate is semidet.
Source rdf_node(?T) is nondet
True when T appears in the subject or object position of a known triple, i.e., is a node in the RDF graph.
Source rdf_create_bnode(--BNode)
Create a new BNode. A blank node is an atom starting with _:. Blank nodes generated by this predicate are of the form _:genid followed by a unique integer.
Source rdf_is_iri(@IRI) is semidet
True if IRI is an RDF IRI term.

For performance reasons, this does not check for compliance to the syntax defined in 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 IRI is present in the database (see rdf_iri/1 for that).

 rdf_is_bnode(@Term) is semidet
True if Term is an RDF blank node identifier.

A blank node is represented by an atom that starts with _:.

Success of this goal does not imply that the blank node is present in the database (see rdf_bnode/1 for that).

For backwards compatibility, atoms that are represented with an atom that starts with __ are also considered to be a blank node.

Source rdf_is_literal(@Term) is semidet
True if Term is an RDF literal term.

An RDF literal term is of the form `String@LanguageTag or Value^^Datatype`.

Success of this goal does not imply that the literal is well-formed or that it is present in the database (see rdf_literal/1 for that).

Source rdf_is_name(@Term) is semidet
True if 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 rdf_name/1 for that).

Source rdf_is_object(@Term) is semidet
True if 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 rdf_object/1 for that).

Since any RDF term can appear in the object position, this is equaivalent to rdf_is_term/1.

Source rdf_is_predicate(@Term) is semidet
True if 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 rdf_predicate/1 for that).

Since only IRIs can appear in the predicate position, this is equivalent to rdf_is_iri/1.

Source rdf_is_subject(@Term) is semidet
True if 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 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 atom(Term).

Source rdf_is_term(@Term) is semidet
True if Term can be used as an RDF term, i.e., if 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 rdf_term/1 for that).

Source rdf_list(?RDFTerm) is semidet
True if RDFTerm is a proper RDF list. This implies that every node in the list has an rdf:first and rdf:rest property and the list ends in rdf:nil.

If RDFTerm is unbound, RDFTerm is bound to each maximal RDF list. An RDF list is maximal if there is no triple rdf(_, rdf:rest, RDFList).

Source rdf_list(+RDFList, -PrologList) is det
True when PrologList represents the rdf:first objects for all cells in RDFList. Note that this can be non-deterministic if cells have multiple rdf:first or rdf:rest triples.
Source rdf_length(+RDFList, -Length:nonneg) is nondet
True when Length is the number of cells in 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.
Source rdf_member(?Member, +RDFList) is nondet
True when Member is a member of RDFList
Source rdf_nextto(?X, ?Y) is nondet
Source rdf_nextto(?X, ?Y, ?RdfList) is nondet
True if Y directly follows X in RdfList.
Source rdf_nth0(?Index, +RDFList, ?X) is nondet
Source rdf_nth1(?Index, +RDFList, ?X) is nondet
True when X is the Index-th element (0-based or 1-based) of RDFList. This predicate is deterministic if Index is given and the list has no multiple rdf:first or rdf:rest values.
Source rdf_last(+RDFList, -Last) is det
True when Last is the last element of RDFList. Note that if the last cell has multiple rdf:first triples, this predicate becomes nondet.
Source rdf_estimate_complexity(?S, ?P, ?O, -Estimate) is det
Source rdf_assert_list(+PrologList, ?RDFList) is det
Source rdf_assert_list(+PrologList, ?RDFList, +Graph) is det
Create an RDF list from the given Prolog List. PrologList must be a proper Prolog list and all members of the list must be acceptable as object for rdf_assert/3. If RDFList is unbound and PrologList is not empty, rdf_create_bnode/1 is used to create RDFList.
Source rdf_retract_list(+RDFList) is det
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.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source rdf(Arg1, Arg2, Arg3, Arg4)
Source rdf_has(Arg1, Arg2, Arg3, Arg4)
Source rdf_update(Arg1, Arg2, Arg3, Arg4, Arg5)
Source rdf_reachable(Arg1, Arg2, Arg3, Arg4, Arg5)
Source rdf_assert(Arg1, Arg2, Arg3, Arg4)
Source rdf_retractall(Arg1, Arg2, Arg3, Arg4)
Source rdf_where(Arg1)
Source rdf_default_graph(Arg1, Arg2)
Source rdf_assert_list(Arg1, Arg2, Arg3)
Source rdf_nextto(Arg1, Arg2, Arg3)
Source rdf_nth1(Arg1, Arg2, Arg3)
 rdf_version(Arg1)
 rdf_resource(Arg1)
 rdf_member_property(Arg1, Arg2)
 rdf_set_predicate(Arg1, Arg2)
 rdf_predicate_property(Arg1, Arg2)
 rdf_transaction(Arg1)
 rdf_transaction(Arg1, Arg2)
 rdf_transaction(Arg1, Arg2, Arg3)
 rdf_active_transaction(Arg1)
 rdf_monitor(Arg1, Arg2)
 rdf_save_db(Arg1)
 rdf_save_db(Arg1, Arg2)
 rdf_load_db(Arg1)
 rdf_reset_db
 rdf_load(Arg1)
 rdf_load(Arg1, Arg2)
 rdf_save(Arg1)
 rdf_save(Arg1, Arg2)
 rdf_unload(Arg1)
 rdf_unload_graph(Arg1)
 rdf_md5(Arg1, Arg2)
 rdf_atom_md5(Arg1, Arg2, Arg3)
 rdf_create_graph(Arg1)
 rdf_graph_property(Arg1, Arg2)
 rdf_set_graph(Arg1, Arg2)
 rdf_graph(Arg1)
 rdf_source(Arg1)
 rdf_source(Arg1, Arg2)
 rdf_make
 rdf_gc
 rdf_source_location(Arg1, Arg2)
 rdf_statistics(Arg1)
 rdf_set(Arg1)
 rdf_generation(Arg1)
 rdf_snapshot(Arg1)
 rdf_delete_snapshot(Arg1)
 rdf_current_snapshot(Arg1)
 rdf_save_subject(Arg1, Arg2, Arg3)
 rdf_save_header(Arg1, Arg2)
 rdf_save_footer(Arg1)
 rdf_equal(Arg1, Arg2)
 lang_equal(Arg1, Arg2)
 lang_matches(Arg1, Arg2)
 rdf_prefix(Arg1, Arg2)
 rdf_current_prefix(Arg1, Arg2)
 rdf_register_prefix(Arg1, Arg2)
 rdf_register_prefix(Arg1, Arg2, Arg3)
 rdf_unregister_prefix(Arg1)
 rdf_current_ns(Arg1, Arg2)
 rdf_register_ns(Arg1, Arg2)
 rdf_register_ns(Arg1, Arg2, Arg3)
 rdf_global_id(Arg1, Arg2)
 rdf_global_object(Arg1, Arg2)
 rdf_global_term(Arg1, Arg2)
 rdf_match_label(Arg1, Arg2, Arg3)
 rdf_split_url(Arg1, Arg2, Arg3)
 rdf_url_namespace(Arg1, Arg2)
 rdf_warm_indexes
 rdf_warm_indexes(Arg1)
 rdf_update_duplicates
 rdf_debug(Arg1)
 rdf_new_literal_map(Arg1)
 rdf_destroy_literal_map(Arg1)
 rdf_reset_literal_map(Arg1)
 rdf_insert_literal_map(Arg1, Arg2, Arg3)
 rdf_insert_literal_map(Arg1, Arg2, Arg3, Arg4)
 rdf_delete_literal_map(Arg1, Arg2, Arg3)
 rdf_delete_literal_map(Arg1, Arg2)
 rdf_find_literal_map(Arg1, Arg2, Arg3)
 rdf_keys_in_literal_map(Arg1, Arg2, Arg3)
 rdf_statistics_literal_map(Arg1, Arg2)
 rdf_graph_prefixes(Arg1, Arg2)
 rdf_graph_prefixes(Arg1, Arg2, Arg3)
 rdf_meta(Arg1)