• Topic
  • Discussion
    • VOS.VOSSparqlProtocol(Last) -- DAVWikiAdmin? , 2017-06-29 07:35:29 Edit
    [TXT]
    [PLAIN]
    [DOCBOOK]
    WebDAV System Administrator 2017-06-29 07:35:29

    Virtuoso SPARQL Query Service

    Introduction to SPARQL in Virtuoso

    The Virtuoso SPARQL query service originally implemented the SPARQL Protocol for RDF (W3C Recommendation, 15 January 2008), and has been updated to support SPARQL 1.1, providing SPARQL query-processing for RDF data available on the open Internet.

    The query service implementation extends the standard protocol by providing multiple output-formats alongside the standard XML results serialization. At present this uses additional query parameters, although content-negotiation will be supported soon.

    SPARQL 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 received on the port specified as 'ServerPort' in the '[HTTPServer]' section of the Virtuoso configuration file which refer to one of these two path strings.

    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/. For example, the Live Virtuoso Demo instance publishes a service at the following endpoint: http://demo.openlinksw.com/sparql/.

    Both GET and POST requests are supported by both server and client. The server recognizes the 'Accept: ...' line of the 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, based on the length of the query text.

    HTTP Request Methods

    Method Supported Notes
    DELETE No
    PUT No
    POST Yes Queries longer than 1900 bytes are POST-ed
    GET Yes Short queries are sent in GET mode

    HTTP Request Parameters

    Parameter Notes Required Occurrence
    query SPARQL Query text Yes
    query-uri Absolute URL for Query Template file that returns SPARQL Query Text No
    default-graph-uri Absolute URL of default graph (string or NULL) Yes
    named-graph-uri 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 Maximum 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
    xslt-uri Absolute URL of XSLT file to be applied to SPARQL Query results No

    HTTP Response Codes

    As specified in the SPARQL protocol, Virtuoso returns the following HTTP response codes:

    Code Meaning
    200 successful query
    400 malformed query
    500 error processing query or fetching data

    HTTP Response Formats

    All standard MIME types of SPARQL Protocol are supported.

    SPARQL Protocol Client Response Formats

    Content-Type SPARQL query type Description
    'application/sparql-results+xml' SELECT, ASK Canonical XML presentation of SPARQL result set
    'text/rdf+n3' CONSTRUCT, DESCRIBE Turtle
    'text/rdf+ttl' CONSTRUCT, DESCRIBE Turtle
    'text/rdf+turtle' CONSTRUCT, DESCRIBE Turtle
    'text/turtle' CONSTRUCT, DESCRIBE Turtle
    'text/n3' CONSTRUCT, DESCRIBE Turtle
    'application/turtle' CONSTRUCT, DESCRIBE Turtle
    'application/x-turtle' CONSTRUCT, DESCRIBE Turtle
    'application/rdf+xml' CONSTRUCT, DESCRIBE Canonical RDF/XML presentation

    SPARQL Protocol Server Response Formats

    Content-Type SPARQL query type Description
    'application/sparql-results+xml' SELECT, ASK Canonical XML presentation of SPARQL result set
    'text/rdf+n3' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'text/rdf+ttl' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'text/rdf+turtle' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'text/turtle' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'text/n3' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'application/turtle' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'application/x-turtle' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle
    'application/x-nice-turtle' SELECT, ASK, CONSTRUCT, DESCRIBE Turtle, like above, but the server will try to use "list" and "[...]" notations to make the document easier to read. This formatting is a slow procedure so long results will be formatted as plain Turtle.
    'text/rdf+nt' SELECT Format for NT (each triple is printed separately without abbreviations)
    'text/plain' SELECT Format for NT (each triple is printed separately without abbreviations)
    'text/ntriples' SELECT, CONSTRUCT, DESCRIBE Format for NT (each triple is printed separately without abbreviations)
    'application/x-trig' SELECT, CONSTRUCT, DESCRIBE TriG? syntax for result sets, triples and quads (or sets of graphs with triples). While it is not used for quads, the output is same as for Turtle.
    'application/rdf+xml' SELECT, CONSTRUCT, DESCRIBE Canonical RDF/XML presentation
    'application/soap+xml' SELECT SOAP XML
    'application/soap+xml;11' SELECT SOAP XML
    'text/html' SELECT HTML document for plain browsing; it's a TABLE for result set and HTML with micro-data for triples
    'text/md+html' SELECT, CONSTRUCT, DESCRIBE HTML with microdata; for triples only
    'text/microdata+html' SELECT, CONSTRUCT, DESCRIBE HTML with microdata; for triples only
    'text/x-html+ul' SELECT, CONSTRUCT, DESCRIBE HTML with triples grouped into hierarchical list
    'text/x-html+tr' SELECT, CONSTRUCT, DESCRIBE HTML with triples in form of a table
    'application/vnd.ms-excel' SELECT HTML table for loading data into stylesheets
    'text/csv' SELECT, CONSTRUCT, DESCRIBE Comma-separated values
    'text/tab-separated-values' SELECT Tab-separated values
    'application/javascript' SELECT JavaScript? data fragment
    'application/json' SELECT JSON
    'application/sparql-results+json' SELECT, ASK JSON result set
    'application/odata+json' SELECT, ASK, CONSTRUCT, DESCRIBE JSON in ODATA style
    'application/microdata+json' SELECT, CONSTRUCT, DESCRIBE Microdata as JSON; for triples only
    'application/rdf+json' CONSTRUCT, DESCRIBE JSON in TALIS style; for triples only
    'application/x-rdf+json' CONSTRUCT, DESCRIBE JSON in TALIS style; for triples only
    'application/x-json+ld' CONSTRUCT, DESCRIBE JSON in Linked Data style; for triples only
    'application/ld+json' CONSTRUCT, DESCRIBE JSON in Linked Data style; for triples only
    'text/cxml' SELECT, CONSTRUCT, DESCRIBE CXML output for rendering in Pivot Viewer of MS SilverLight?. Result sets and triples are handled in different ways.
    'text/cxml+qrcode' SELECT,CONSTRUCT, DESCRIBE CXML output with QRcode imprinted into each picture; for result sets and triples
    'application/atom+xml' SELECT, CONSTRUCT, DESCRIBE Atom-style XML
    'application/xhtml+xml' SELECT RDFa placed into XHTML; for triples only

    If the HTTP header returned by the remote server does not contain a 'Content-Type' line, the MIME-type may be deduced from the text of the returned body. 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.

    Additional HTTP Response Formats -- SELECT

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

    Format Value Description Content-Type
    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
    Javascript 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
    XML application/sparql-results+xml
    TURTLE text/rdf+n3

    Additional HTTP Response Formats -- DESCRIBE & CONSTRUCT

    Format Value Description Content-Type
    JSON application/rdf+json

    Virtuoso/PL APIs

    Virtuoso also provides SPARQL Protocol client APIs in PL, so you can communicate with SPARQL Query Services from within SQL stored-procedures. The APIs are as follows:

    API 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.

    Examples

    There is a live Virtuoso Demo Server instance available at all times for experimentation and demonstrations. It includes a collection of saved queries demonstrating Virtuoso's implementation of the DAWG's SPARQL test-suite -- a collection of SPARQL query language use-cases that enables interactive and simplified testing of a RDF triple-store's SPARQL implementation.

    Virtuoso also powers the publicly accessible endpoints housing datasets for DBpedia, the LOD Cloud Cache, and URIBurner.

    Implementation Notes

    This service has been implemented using OpenLink Virtuoso.

    Related