Virtuoso R2RML → Quad Map / RDF View How-To Guide

Virtuoso Universal Server Tips, Tricks, and HowTos
, , ,
1

Virtuoso R2RML → Quad Map / RDF View How-To Guide

This guide explains how to create RDF Views in Virtuoso from R2RML mapping graphs using the DB.DBA.R2RML_MAKE_QM_FROM_G() function, including:

  • Function prototype
  • Example usage on a sample PRODUCT table
  • How to control and identify the Quad Map names
  • How to list and remove Quad Maps
  • Notes on clearing vs deleting

1. Function Prototype

DB.DBA.R2RML_MAKE_QM_FROM_G (
    IN r2rml_graph           VARCHAR,   -- source graph IRI containing R2RML TTL
    IN target_graph_or_null  VARCHAR := NULL,   -- optional explicit target graph
    IN qm_iri                VARCHAR := NULL    -- optional explicit QuadMap IRI
) RETURNS VARCHAR
  • r2rml_graph: IRI of the graph with your R2RML mapping.
  • target_graph_or_null: optional target graph (usually left NULL).
  • qm_iri: optional explicit name for the Quad Map (otherwise Virtuoso generates a urn:qm:<hash>).

The function returns the SPARQL DDL commands needed to create the Quad Map, which are then executed to deploy the RDF View.

2. Sample R2RML Mapping (PRODUCT)

This online sample uses a simple table R2RML.TEST.PRODUCT:

CREATE TABLE "R2RML"."TEST"."PRODUCT"
(
  id   INTEGER PRIMARY KEY,
  name VARCHAR(100)
);

INSERT SOFT "R2RML"."TEST"."PRODUCT" VALUES (1, 'Virtuoso');

With this R2RML mapping in Turtle:

@prefix rr:  <http://www.w3.org/ns/r2rml#> .
@prefix exa: <http://example.com/ns#> .
@prefix product: <http://example.com/product#> .

<http://example.com/ns#TriplesMap1>
  a rr:TriplesMap ;
  rr:logicalTable [
      rr:tableSchema "R2RML" ;
      rr:tableOwner  "TEST" ;
      rr:tableName   "PRODUCT"
  ] ;
  rr:subjectMap [
      rr:template "http://example.com/product/{id}" ;
      rr:class exa:product ;
      rr:graph <http://example.com/>
  ] ;
  rr:predicateObjectMap [
      rr:predicate product:id ;
      rr:objectMap [ rr:column "id" ]
  ] ;
  rr:predicateObjectMap [
      rr:predicate product:name ;
      rr:objectMap [ rr:column "name" ]
  ] .

This mapping defines an RDF view of PRODUCT rows, producing triples like:

<http://example.com/product/1> a exa:product ;
                                product:id 1 ;
                                product:name "Virtuoso" .

Load it into Virtuoso using TTLP() to a graph location (e.g., http://r2rml/product.n3).

3. Load R2RML Mapping into Virtuoso

DB.DBA.TTLP(
  '*** R2RML Turtle content here as a string ***',
  '',
  'http://r2rml/product.n3'
);

This stores the R2RML mapping as triples in graph http://r2rml/product.n3.

4. Create Quad Map (RDF View)

A) Without Explicit Name

EXEC ('SPARQL ' ||
      DB.DBA.R2RML_MAKE_QM_FROM_G('http://r2rml/product.n3'));

Virtuoso will generate a Quad Map with a hash-based name, e.g.:

urn:qm:5a7b1fe7d...

B) With Explicit Quad Map Name

Better to specify your own IRI for clarity:

EXEC ('SPARQL ' ||
      DB.DBA.R2RML_MAKE_QM_FROM_G(
            'http://r2rml/product.n3',
            NULL,
            'urn:qm:product:main'
      )
);

This creates a Quad Map with name:

urn:qm:product:main

instead of a random hash-based one.

5. Inspect the Generated Quad Map

After running the above, you can query the virtual graph:

SPARQL
SELECT * FROM <http://example.com/> WHERE { ?s ?p ?o };

Example output:

http://example.com/product/1  product:id   1
http://example.com/product/1  product:name "Virtuoso"
http://example.com/product/1  rdf:type    exa:product

6. List Quad Maps and Associated Graphs

A) List Quad Maps

SPARQL
DEFINE input:storage ""
SELECT ?qm
FROM virtrdf:
WHERE {
  [] virtrdf:qsUserMaps ?maps .
  ?maps ?p ?qm .
  ?qm a virtrdf:QuadMap .
};

B) List Quad Maps with Graph IRI

SPARQL
DEFINE input:storage ""
SELECT ?qm ?gr
FROM virtrdf:
WHERE {
  [] virtrdf:qsUserMaps ?maps .
  ?maps ?p ?qm .
  ?qm a virtrdf:QuadMap .
  ?qm virtrdf:qmGraphRange-rvrFixedValue ?gr .
};

This returns:

qm (Quad Map IRI) gr (Target Graph)
urn:qm:product:main http://example.com/

7. Drop / Delete Quad Map (RDF View)

A) Why CLEAR GRAPH Is Not Enough

Doing:

SPARQL CLEAR GRAPH <http://example.com/>;

only removes materialized triples in the graph alias — it does not remove the Quad Map definition that generates virtual triples.

B) Correct Way to Drop the Quad Map

You must use:

SPARQL DROP QUAD MAP <urn:qm:product:main>;

or, if no explicit name was provided, with the generated name you discovered:

SPARQL DROP QUAD MAP <urn:qm:5a7b1fe7d...>;

This removes the Quad Map definition from the Quad Storage so that subsequent SPARQL queries no longer return data from that view.

C) Verify Removal

After dropping:

SPARQL
SELECT COUNT(*)
FROM <http://example.com/>
WHERE { ?s ?p ?o };

Result should be:

0

8. Summary

Task Command
Load R2RML mapping DB.DBA.TTLP(...)
Generate Quad Map (default) DB.DBA.R2RML_MAKE_QM_FROM_G(url)
Generate Quad Map with specific name pass 3rd param (qm_iri)
List Quad Maps SPARQL on virtrdf:
Drop RDF View SPARQL DROP QUAD MAP <qmIri>
Clear triples only SPARQL CLEAR GRAPH <graphIri>

Related