Linked Data Views: create literal documentation

Virtuoso Universal Server RDF Data Management
1

Hi All,

I have a date column, which on returning from sparql returns a date in a timezone.
e.g.

“2020-01-01+01:00”^^xsd:date
from a value like
2020.1.1
in the sql column

The documentation at 16.5.3. Quad Map Patterns, Values and IRI Classes does not suggest any options.

The musicbrainz example suggests things are possible.

Regards,
Jerven

2

The management of literals in Virtuoso can be achieved through the use of a ‘literal class’, which provides a structured way to handle data transformations between SQL and RDF formats. Although this is not extensively documented, examples from the RDF-H test suite and the MusicBrainz demo illustrate the concept well.

Example from RDF-H Test Suite

In the RDF-H test suite, a literal class is defined using functions for mapping and inverse mapping. The CREATE LITERAL CLASS statement establishes a new literal class with these functions. The mapping function converts an SQL integer to a formatted literal string, using sprintf to create a URI-like structure based on the user’s role. The inverse mapping function performs the reverse operation, converting a formatted literal back into an SQL integer, ensuring it matches the column value in the SQL table.

Example from MusicBrainz Demo

The MusicBrainz demo provides a clearer example of how a literal class is defined and the purpose of the PL mapping functions. In this example, the mapping function appends a time component to a date string, converting it into a xsd:dateTime format. The inverse mapping function removes the time component, converting the xsd:dateTime back to a simple date string.

Additionally, the literal class can have options to declare a datatype or language. For instance, you can specify the datatype for the literal, such as xsd:dateTime, or a language tag for string literals.

Understanding IRI Classes

IRI Classes in Virtuoso are used to define how SQL data is mapped to RDF IRIs (Internationalized Resource Identifiers) and vice versa. They play a crucial role in ensuring that each SQL entity is uniquely represented in RDF format. The purpose of an IRI Class is to maintain a consistent and unique mapping between SQL data and RDF IRIs, which is essential for data integration and interoperability in semantic web applications.

  • Nature of IRI Classes: IRI Classes define the transformation rules for converting SQL data into RDF IRIs. This involves specifying how SQL identifiers are translated into unique RDF identifiers, ensuring that each SQL entity corresponds to a distinct RDF IRI.
  • Purpose of IRI Classes: The primary purpose of IRI Classes is to facilitate seamless data exchange between SQL databases and RDF-based systems. By defining a one-to-one mapping, IRI Classes ensure that data integrity is maintained across different data representations.

Summary of Options

The following options are applicable:

  • IRI Class Options:
    • BIJECTION: Ensures a one-to-one mapping between SQL and RDF representations, meaning each SQL value corresponds to a unique RDF representation and vice versa.
    • RETURNS: Specifies expected sprintf patterns for the IRI, allowing for flexible and precise IRI generation.
  • Literal Class Options:
    • BIJECTION: Similar to IRI classes, ensures a one-to-one mapping between SQL literals and RDF literals.
    • DATATYPE <dt_iri>: Declares the datatype of the literal.
    • LANG "lang_tag": Specifies the language tag for string literals.
    • RETURNS: Uses special syntax for possible sprintf patterns, allowing multiple patterns with a union, such as OPTION( RETURNS 'sprintf_pattern_1' union 'sprintf_pattern_2' ).

Example:
An example of using the RETURNS option is OPTION (bijection, returns "http://%U/sys/group?id=%d" union "http://%U/sys/member?id=%d"), which specifies multiple patterns for mapping.

Conclusion:

The syntax provides a mechanism to map literals to another form using sprintf-like functions and an inverse function to convert from an external format back to an SQL value. This approach allows for flexible handling of literals, including date values with timezones, by defining custom mapping logic and specifying options for datatype and language. IRI Classes, in particular, ensure that SQL data is accurately and uniquely represented in RDF format, supporting robust data integration and interoperability.

1 Like
3

Thank you @hwilliams that is super helpful.

This helped solve my problem with a date column having a timezone in the default mapping.

 CREATE FUNCTION DB.DBA.DATE_WITHOUT_TIMEZONE (in d varchar) {
     return stringdate(d);
  };

  CREATE FUNCTION DB.DBA.DATE_WITHOUT_TIMEZONE_INVERSE (in d DATE) {
     return substring(cast(d as varchar), 1, 10);
  }

  SPARQL CREATE LITERAL CLASS <https://sparql.uniprot.org/sql-mapping/dateNoTz> USING
     FUNCTION DB.DBA.DATE_WITHOUT_TIMEZONE (IN d VARCHAR) RETURNS DATE,
     FUNCTION DB.DBA.DATE_WITHOUT_TIMEZONE_INVERSE (IN d DATE) RETURNS VARCHAR
     OPTION (datatype <http://www.w3.org/2001/XMLSchema#date>);

Similar for xsd:boolean instead of xsd:int

CREATE FUNCTION DB.DBA.BOOL_NOT_INT(in b INTEGER) {
  if (b = 1){
    return 'true';
  } else {
return 'false';
  }
}

CREATE FUNCTION DB.DBA.BOOL_NOT_INT_INVERSE (in b VARCHAR) {
  if (b = 'true'){
    return 1;
  } else {
    return 0;
  }
}

with a grant to execute for the user SPARQL

GRANT EXECUTE ON DB.DBA.BOOL_NOT_INT TO "SPARQL"
GRANT EXECUTE ON DB.DBA.BOOL_NOT_INT TO "SPARQL"

select 1, BOOL_NOT_INT(1), BOOL_NOT_INT_INVERSE('true');

obsolete          BOOL_NOT_INT                                                                      BOOL_NOT_INT_INVERSE
INTEGER NOT NULL  LONG VARCHAR                                                                      LONG VARCHAR
1                 true                                                                              1