# 14. RDF Database and SPARQL

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
RDF Database and SPARQL
Data Representation
RDF and SPARQL API and SQL
IRI Dereferencing
RDF Views -- Mapping Relational Data to RDF
SPARQL Implementation
RDF Inference in Virtuoso
Using Full Text Search in SPARQL
Aggregates in SPARQL
Virtuoso SPARQL Query Service
Introduction Service Endpoint Request Methods Functions Request Parameters Response Codes Response Format Additional Response Formats -- SELECT Examples Implementation Notes Virtuoso Semantic Bank end point RDF proxy service

## 14.9. Virtuoso SPARQL Query Service

### 14.9.1. Introduction

The Virtuoso SPARQL query service implements the SPARQL Protocol for RDF (W3C Working Draft 25 January 2006) providing SPARQL query processing for RDF data available on the open internet.

The query processor extends the standard protocol to provide support for multiple output formats. At present this uses additional query parameters.

Supported features include

- GET and POST requests;
- variety of transfer MIME-types, including RDF /XML and TURTLE;
- default-graph-uri environment parameter;
- all sorts of queries including CONSTRUCT and DESCRIBE.

### 14.9.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.

### 14.9.3. Request Methods

Table: 14.9.3.1. Methods List
Method | Supported? | Notes
--- | --- | ---
GET | Yes | short queries are sent in GET mode
POST | Yes | Queries longer than 1900 bytes are POST-ed.
DELETE | No |
PUT | No |

### 14.9.4. Functions

The SPARQL client can be invoked by three similar functions:

Table: 14.9.4.1. Functions List
Function | Notes
--- | ---
DB.DBA.SPARQL_REXEC | behaves like DBA.SPARQL_EVAL, but executes the query on the specified server. The procedure does not return anything. Instead, it creates a result set.
DB.DBA.SPARQL_REXEC_TO_ARRAY | behaves like DBA.SPARQL_EXEC_TO_ARRAY (), but executes the query on the specified server. The function return a vector of rows, where every row is represented by a vector of values of fields.

DB.DBA.SPARQL_REXEC_WITH_META

has no local 'SPARQL_EVAL' analog. It produces not only an array of result rows but also array of metadata about result set in a format used by the exec () function. This function can be used when the result should be passed later to exec_result_names () and exec_result () built-in functions. To process local query in similar style, an application can use plain SQL built-in function exec (): an SPARQL query (with 'SPARQL' keyword in front) can be passed to exec () instead of text of plain SQL SELECT statement.

    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.

### 14.9.5. Request Parameters

Table: 14.9.5.1. Request Parameters List
Parameter | Notes | Required? | Occurrence
--- | --- | --- | ---
service | service URI such as 'http://example.com/sparql/' | Yes |
query | text of the query | Yes |
dflt_graph | default graph URI (string or NULL) | No |
named_graphs | vector of named graphs (or NULL to not override what's specified in the query | Yes |
req_hdr | additional HTTP header lines that should be passed to the service; 'Host: ...' is most popular | No |
maxrows | limit on numbers of rows that should be returned (actual size of result set may differ) | No |
bnode_dict | dictionary of known blank node names, or NULL for usual loading | No |

### 14.9.6. 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.

### 14.9.7. Response Format

All standard MIME types of SPARQL Protocol are supported:

Table: 14.9.7.1. Supported MIME Types list
Mimetype | Supported for result of Query
--- | ---
'application/sparql-results+xml' | SELECT
'application/sparql-results+xml' | ASK
'application/rdf+xml' | CONSTRUCT
'application/rdf+xml' | DESCRIBE
'text/rdf+n3' | CONSTRUCT
'text/rdf+n3' | DESCRIBE

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.

### 14.9.8. Additional Response Formats -- SELECT

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

Table: 14.9.8.1. Additional Response formats list
Format Value | Description | Mimetype
--- | --- | ---
HTML | HTML document containing query summary and tabular results | text/html
json | JSON serialization of results. Conforms to the draft specification Serializing SPARQL Query Results in JSON | application/sparql-results+json
js | Javascript serialization of results. Generates an HTML table with the CSS class sparql. The table contains a column indicating row number and additional columns for each query variable. Each query solution contributes one row of the table. Unbound variables are indicated with a non-breaking space in the appropriate table cells. | application/javascript
table |  | text/html
XML |  | text/html
TURTLE |  | text/html

### 14.9.9. Examples

Virtuoso's SPARQL Implementation Demo offers a live demonstration of Virtuoso's implementation of DAWG's SPARQL test-suite; a collection of SPARQL query language use-cases that enable interactive and simplified testing of a Triple Store's implementation. Can be found at 'http://example.com:8080/sparql_demo/' depending on the local Virtuoso Server Configuration, or live at Virtuoso Demo Server.

### 14.9.10. Implementation Notes

This service has been implemented using Virtuoso Server.

### 14.9.11. 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 facetted 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:

"http://simile.mit.edu/dist/semantic-bank/

The Virtuoso Semantic Bank end point.

Before you can publish, you must register with one or more Semantic Banks:

- Invoke the menu command Tools » Piggy Bank » My Semantic Bank Accounts....
- Click Add... in the Semantic Bank Accounts dialog box.
- In the popup dialog box, type in the URL to the Virtuoso Semantic Bank you want to register with. Example: http://servar_name:server_port/bank
- Enter an account a valid Virtuoso DAV user. (Note: currently we do not use encryption during authentication; do not use your precious password here.)
- Click OK, wait for the account to get registered, and then dismiss the Semantic Bank Accounts dialog box.
- To publish an item, just click the corresponding Publish button (much like how you save the item). To publish all the items being viewed, click the Publish All button.

What is the Graph Name used by Virtuoso for the Triples from PiggyBank?

http://simile.org/piggybank/<piggybank-generated-name>

The piggybank-generated-name is Virtuoso DAV user.

### 14.9.12. 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.

Virtuoso reserves the path '/proxy/' 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/proxy/'.

The RDF proxy service takes following URL parameters:

- url the URL of the target
- 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.

Previous Aggregates in SPARQL | Chapter Contents | Next Contents of Web Services