15. RDF Data Access and Data Management

15.11. Virtuoso SPARQL Query Service

15.11.1. Introduction

15.11.2. Service Endpoint

Virtuoso reserves the path '/sparql/' and a synonym path '/SPARQL/' for SPARQL service.

In the current implementation, Virtuoso defines virtual directories for HTTP requests that come to the port specified as 'ServerPort' in the '[HTTPServer]' section of Virtuoso configuration file and refer to one of these two path strings. So if the Virtuoso installation on host example.com listens for HTTP requests on port 8080 then client applications should use the 'service endpoint' string equal to 'http://example.com:8080/sparql/'.

Both GET and POST requests are supported by both server and client. The server recognizes the 'Accept: ...' line of request header to find MIME types preferred by the connected client and adjust the output mode of the response.

The client chooses between GET and POST automatically, using the length of query text as a criterion.

If the SPARQL endpoint is accessed without any URL and query entered, will be shown page with interactive query form.

15.11.3. Service Endpoint with authenticated SPARUL option

Virtuoso reserves the path '/sparql-auth/' for SPARQL service with authenticated SPARUL option.

This endpoint allows specific SQL accounts to perform SPARUL over the SPARQL protocol.

"SPARQL_UPDATE" is needed to be granted on a user to perform all operations on physical triples and the user to be able allowed to perform SQL/ODBC logins:

• Go to the Virtuoso Administration Conductor i.e. http://host:port/conductor
• Login as dba user
• Go to System Admin->User Accounts->Users

  Figure: 15.11.3.1. Conductor UI

• Click the link "Edit"
• In the shown form check the "Allow SQL/ODBC Logins" check-box.
• Select from the list of available Account Roles "SPARQL_UPDATE" role and click the ">>" button so to add it to the right-positioned list.

Figure: 15.11.3.1. Conductor UI

• Click the "Save" button.

Note that if there is a table used in a RDF view, and this table is not granted to SPARQL_SELECT ( SPARQL_UPDATE inherits it ), then select on all graph will return access violation error as the user account has no permissions to read it. Thus the account need to have privileges on all tables included in any rdf view in order to be able to select on *all* graphs.

15.11.4. Request Methods

15.11.5. Functions

The SPARQL client can be invoked by three similar functions:

create procedure DB.DBA.SPARQL_REXEC (
    in service varchar, in query varchar, in dflt_graph varchar, in named_graphs any,
    in req_hdr any, in maxrows integer, in bnode_dict any );

create function DB.DBA.SPARQL_REXEC_TO_ARRAY (
    in service varchar, in query varchar, in dflt_graph varchar, in named_graphs any,
    in req_hdr any, in maxrows integer, in bnode_dict any )
    returns any;

create procedure DB.DBA.SPARQL_REXEC_WITH_META (
    in service varchar, in query varchar, in dflt_graph varchar, in named_graphs any,
    in req_hdr any, in maxrows integer, in bnode_dict any,
    out metadata any,  -- metadata like exec () returns.
    out resultset any) -- results as 'long valmode' values.

15.11.6. Request Parameters

15.11.7. Response Codes

If the query is a CONSTRUCT or DESCRIBE then the result set consists of a single row and a single column, the value inside is a dictionary of triples in 'long valmode'. Note that the dictionary object can not be sent to SQL client, say, via ODBC. The client can loose database connection trying to fetch a result set row that contain a dictionary object. This disconnect will be safe for server, so the client can re-connect to the server, but the disconnected transaction will be rolled back.

15.11.8. Response Format

All standard MIME types of SPARQL Protocol are supported:

If the HTTP header returned by the remote server does not contain 'Content-Type' line, the MIME type may be guessed from the text of the returned body.

The current implementation does not support results of SELECT returned in RDF /XML, TURTLE or 'sparql-results-2'.

Error messages returned from the service are returned as XML documents, using the mime type application/xml. The documents consist of a single element containing an error message.

15.11.9. Additional Response Formats -- SELECT

Use the format parameter to select one of the following alternate output formats:

15.11.10. Examples

15.11.11. Implementation Notes

15.11.12. Virtuoso Semantic Bank end point

What is Piggy Bank?

Piggy Bank is an extension to the Firefox Web browser that turns it into a “Semantic Web browser, letting you make use of existing information on the Web in more useful and flexible ways not offered by the original Web sites.

What is Semantic Bank?

Semantic Bank is the server companion of Piggy Bank that lets you persist, share and publish data collected by individuals, groups or communities. Here is a screen shot of one in action:

What can I do with this?

A Semantic Bank allows you to:

persist your information remotely on a server. This is useful, for example, if you want to share data between two of your computers or to avoid losing it due to mistakes or failure.

share information with other people. The ability to tag resources creates a powerful serendipitous categorization (as proven by things like del.icio.us or Flickr).

lets you publish your information, both in the "pure" RDF form (for those who know how to make use of it) or to regular web pages, with the usual Longwell faceted browsing view of it

How can I help?

Semantic Bank is an open source software and built around the spirit of open participation and collaboration.

There are several ways you can help:

• Install a Semantic Bank and lets us know about it, so that we can update the list of available Semantic Banks.
• Subscribe to our mailing lists to show your interest and give us feedback
• Report problems and ask for new features through our issue tracking system.
• Send us patches or fixes to the code

Licensing and Legal Issues

Semantic Bank is open source software and is licensed under the BSD license.

Note, however, that this software ships with libraries that are not released under the same license; that we interpret their licensing terms to be compatible with ours and that we are redistributing them unmodified. For more information on the licensing terms of the libraries Semantic Bank depends on, please refer to the source code.

Download location:

15.11.13. Making RDF View Dereferenceable -- Northwind example

15.11.14. RDF proxy service

In certain cases like for Ajax applications, it's prohibited to issue HTTP requests to another server that origin server. In other cases it is needed to transform the content of target to an RDF format. To this purpose the Virtuoso Server provide a RDF proxy service. This service takes as argument target URL and may return content as-is or will try to transform with SPARQL sponger and return RDF data representing the target. In case of transformation to RDF the serialization of the output can be forced by a URL parameter of by content negotiation.

When the rdf_mappers package is installed, Virtuoso reserves the path '/about/[rdf|html]/' for RDF proxy service. In the current implementation, Virtuoso defines virtual directories for HTTP requests that come to the port specified as 'ServerPort' in the '[HTTPServer]' section of Virtuoso configuration file and refer to the above path string. So if the Virtuoso installation on host example.com listens for HTTP requests on port 8080 then client applications should use the 'service endpoint' string equal to 'http://example.com:8080/about/[rdf|html]/'.

If the rdf_mappers package is not installed, then the path '/proxy/rdf/' is used for RDF proxy service.

The old pattern '/proxy/' for RDF proxy service is deprecated.

Note: In order the RDF proxy service to work correctly, in case you do not have the rdf_mappers package installed, you need to enable SPARQL_UPDATE and grant RDF_SPONGE_UP for SPARQL user:

enable SPARQL_UPDATE using Conductor UI:

• Go to the Virtuoso Administration Conductor i.e. http://host:port/conductor
• Login as dba user
• Go to System Admin->User Accounts->Roles

Figure: 15.11.14.1. Conductor UI

• Click the link "Edit" for "SPARQL_UPDATE
• Select from the list of available user/groups "SPARQL" and click the ">>" button so to add it to the right-positioned list.

Figure: 15.11.14.2. Conductor UI

• Click the button "Update".

grant RDF_SPONGE_UP:

grant execute on DB.DBA.RDF_SPONGE_UP to "SPARQL";

The RDF proxy service takes following URL parameters when using the style: http://host:port/proxy?..:

• force if 'rdf' is specified will try to extract RDF data from target and return it
• header HTTP headers to be sent to the target
• output-format if 'force=rdf' is given, designate the output MIME type of the RDF data, the default is 'rdf+xml', can be also 'n3' or 'turtle' or 'ttl'.

When no 'output-format' is given and RDF data is asked, the result will be serialized with MIME type depending of 'Accept' header i.e. the proxy service will do content negotiation.

Example: rdf file with URL: http://www.w3.org/People/Berners-Lee/card

-- Access the url in order to view the result in html format:
http://host:port/about/html/http://www.w3.org/People/Berners-Lee/card
-- Access the url in order to view the result in rdf:
http://host:port/about/rdf/http://www.w3.org/People/Berners-Lee/card
-- or use the style:
http://host:port/proxy/rdf/http://www.w3.org/People/Berners-Lee/card
-- or use the style:
http://host:port/proxy?url=http://www.w3.org/People/Berners-Lee/card&force=rdf

Note: It is not allowed when using the style http://host:port/proxy/rdf to pass url parameters to the proxy.

Now go to the sparql endpoint, i.e. http://host:port/sparql

Enter for Default Graph URI the url of the rdf file: http://www.w3.org/People/Berners-Lee/card

Enter for Query:

SELECT * WHERE {?s ?p ?o}

As result will be shown the saved triples:

s  	                                        p  	                                           o
http://www.w3.org/People/Berners-Lee/card 	http://www.w3.org/1999/02/22-rdf-syntax-ns#type    http://xmlns.com/foaf/0.1/PersonalProfileDocument
http://www.w3.org/People/Berners-Lee/card 	http://purl.org/dc/elements/1.1/title 	           Tim Berners-Lee's FOAF file
http://www.w3.org/People/Berners-Lee/card 	http://creativecommons.org/ns#license 	           http://creativecommons.org/licenses/by-nc/3.0/
http://www.w3.org/People/Berners-Lee/card 	http://xmlns.com/foaf/0.1/maker 	           http://www.w3.org/People/Berners-Lee/card#i
etc ...

15.11.15. SPARQL ini service

The SPARQL INI section values can be get as RDF via http://cname/sparql?ini

Example: http://demo.openlinksw.com/sparql?ini

<?xml version="1.0" encoding="utf-8" ?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:MaxQueryCostEstimationTime xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">1000</ns0pred:MaxQueryCostEstimationTime></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:ExternalXsltSource xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">1</ns0pred:ExternalXsltSource></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:DefaultQuery xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">select ?Subject ?Concept where {?Subject a ?Concept}</ns0pred:DefaultQuery></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:ResultSetMaxRows xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">100000</ns0pred:ResultSetMaxRows></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:MaxQueryExecutionTime xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">30</ns0pred:MaxQueryExecutionTime></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:ExternalQuerySource xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">1</ns0pred:ExternalQuerySource></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:DefaultGraph xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">http://demo.openlinksw.com/dataspace/person/demo</ns0pred:DefaultGraph></rdf:Description>
<rdf:Description rdf:about="http://www.openlinksw.com/schemas/virtini#SPARQL"><ns0pred:PingService xmlns:ns0pred="http://www.openlinksw.com/schemas/virtini#">http://rpc.pingthesemanticweb.com/</ns0pred:PingService></rdf:Description>
</rdf:RDF>

15.11.16. SPARQL OAuth Endpoint

OAuth provides a secure data transmmission level mechanism for your SPARQL endpoint. It enables you to securely interact with your RDF database from a variety of locations. It also allows you to provide controlled access to private data to select user profiles.

Virtuoso OAuth server can be installed by installing the oauth_dav.vad package and the OAuth UI is accessible from the URL http://cname:port/oauth

The user must have SQL privileges in order to run secured SPARQL statements.

Here is a sample scenario:

1. Install the conductor_dav.vad and oauth_dav.vad packages.
2. From the Conductor UI create user test1 by setting SQL and DAV login enable. Also set SPARQL_UPDATE role to it:
   1. Go to http://cname:port/conductor
   2. Log in as dba user
   3. Go to System Admin->User Account and click the "Create New Account" link

      Figure: 15.11.16.1. Conductor UI

   4. In the shown form:
      1. Enter user name for ex. test1, password and confirm password
      2. Check "Allow DAV Logins"
      3. Check "Allow SQL/ODBC Logins"
      4. Add Role "SPARQL_UPDATE" from the list of available Roles to the "Selected" box.

         Figure: 15.11.16.1. Conductor UI

   5. Click the "Save" button.
   6. As result the user test1 will be created.

      Figure: 15.11.16.1. Conductor UI

3. Go to http://cname:port/oauth/

   Figure: 15.11.16.1. OAuth UI

4. Click the "OAuth keys" link
5. Log in as user test1

   Figure: 15.11.16.1. OAuth UI

6. As result will be shown the OAuth application registration form.

   Figure: 15.11.16.1. OAuth UI

7. Generate key for SPARQL by selecting it from the list of "Application name" and click the "Generate Keys" button.
8. As result for SPARQL will be generated Consumer Key for ex.:

   cf92411e17f59960a4189451bfb5bf6b92c856e3
   

   Figure: 15.11.16.1. OAuth UI

9. Click the "Back to main menu" link.
10. Click the "Protected SPARQL Endpoint" link.
11. As result will be shown the OpenLink Virtuoso SPARQL Query form.

    Figure: 15.11.16.1. OAuth UI

12. Enter for Default Graph URI this:

    http://myopenlink.net/dataspace/person/kidehen#this
    

13. Enter for "OAuth token" field the value:

    cf92411e17f59960a4189451bfb5bf6b92c856e3
    

    Figure: 15.11.16.1. OAuth UI

14. Click the "Run Query" button.
15. In the shown OAuth Authorization Service form enter the password for user test1 and click the "Login" button.

    Figure: 15.11.16.1. OAuth UI

16. In the shown form click the "Authorize" button.

    Figure: 15.11.16.1. OAuth UI

17. As results will be shown the found results:

    Figure: 15.11.16.1. OAuth UI

15.11.17. SPARQL Endpoint with Excel mime-type output option

The SPARQL Endpoint offers an Excel mime-type output option.

From http://cname:host/sparql select for "Display Results As:" Spreadsheet and click the "Run Query" button.

Figure: 15.11.17.1. SPARQL Endpoint with Excel mime-type output

15.11.18. SPARQL Endpoint with JSON+RDF

The SPARQL Endpoint offers JSON+RDF output option.

From http://cname:host/sparql select for "Display Results As:" JSON and click the "Run Query" button.

Figure: 15.11.18.1. SPARQL Endpoint with JSON+RDF output

As result URL containg as parameter the format application/sparql-results+json will be generated and the content should look like:

Figure: 15.11.18.2. SPARQL Endpoint with JSON+RDF