Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Integrated Ruby SPARQL library

branch: master
README.markdown

SPARQL for RDF.rb

This is a Ruby implementation of SPARQL for RDF.rb.

Features

  • 100% free and unencumbered public domain software.
  • SPARQL 1.0 query parsing and execution
  • SPARQL results as XML, JSON or HTML.
  • SPARQL CONSTRUCT or DESCRIBE serialized based on Format, Extension of Mime Type using available RDF Writers (see Linked Data)
  • SPARQL Client for accessing remote SPARQL endpoints.
  • Rack and Sinatra middleware to perform HTTP content negotiation for result formats
  • Compatible with Ruby 1.9.x.
  • Compatible with older Ruby versions with the help of the Backports gem.
  • Supports Unicode query strings both on Ruby 1.8.x and 1.9.x.

Description

The {SPARQL} gem implements [SPARQL 1.0 Query] and provides Rack and Sinatra middleware to provide results using HTTP Content Negotiation.

  • {SPARQL::Grammar} implements a [SPARQL 1.0 Query] parser generating SPARQL S-Expressions (SSE).
  • {SPARQL::Algebra} executes SSE against Any RDF::Graph or RDF::Repository, including compliant RDF.rb repository adaptors such as RDF::DO and RDF::Mongo.
  • {Rack::SPARQL} and {Sinatra::SPARQL} provide middleware components to format results using an appropriate format based on HTTP content negotiation.

Middleware

Rack::SPARQL is a superset of Rack::LinkedData to allow content negotiated results to be returned any RDF::Enumerable or RDF::Query::Solutions compatible results. You would typically return an instance of RDF::Graph, RDF::Repository or RDF::Query::Solutions from your Rack application, and let the Rack::SPARQL::ContentNegotiation middleware take care of serializing your response into whatever format the HTTP client requested and understands.

Sinatra::SPARQL is a thin Sinatra-specific wrapper around the {Rack::SPARQL} middleware, which implements SPARQL content negotiation for Rack applications.

The middleware queries RDF.rb for the MIME content types of known RDF serialization formats, so it will work with whatever serialization plugins that are currently available for RDF.rb. (At present, this includes support for N-Triples, N-Quads, Turtle, RDF/XML, RDF/JSON, JSON-LD, RDFa, TriG and TriX.)

Remote datasets

A SPARQL query containing FROM or FROM NAMED will load the referenced IRI unless the repository already contains a context with that same IRI. This is performed using RDF.rb RDF::Util::File.open_file passing HTTP Accept headers for various available RDF formats. For best results, require Linked Data to enable a full set of RDF formats in the GET request. Also, consider overriding RDF::Util::File.open_file with an implementation with support for HTTP Get headers (such as Net::HTTP).

Result formats

{SPARQL.serialize_results} may be used on it's own, or in conjunction with {Rack::SPARQL} or {Sinatra::SPARQL} to provide content-negotiated query results. For basic SELECT and ASK this includes HTML, XML and JSON formats. DESCRIBE and CONSTRUCT create an RDF::Graph, which can be serialized through HTTP Content Netogiation using available RDF writers. For best results, require Linked Data to enable a full set of RDF formats.

Examples

require 'rubygems'
require 'sparql'

Executing a SPARQL query against a repository

queryable = RDF::Repository.load("etc/doap.ttl")
sse = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
sse.execute(queryable)

Rendering solutions as JSON, XML or HTML

queryable = RDF::Repository.load("etc/doap.ttl")
solutions = SPARQL.execute("SELECT * WHERE { ?s ?p ?o }", queryable)
solutions.to_json #to_xml #to_html

Parsing a SPARQL query string to SSE

sse = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
sse.to_sxp

Command line processing

sparql --default-graph etc/doap.ttl etc/from_default.rq
sparql -e "SELECT * FROM <etc/doap.ttl> WHERE { ?s ?p ?o }"

# Generate SPARQL Algebra Expression (SSE) format
sparql --to-sse etc/input.rq
sparql --to-sse -e "SELECT * WHERE { ?s ?p ?o }"

# Run query using SSE input
sparql --default-graph etc/doap.ttl --sse etc/input.sse
sparql --sse -e "(dataset (<etc/doap.ttl>) (bgp (triple ?s ?p ?o))))"

Adding SPARQL content negotiation to a Rails 3.x application

# config/application.rb
require 'rack/sparql'

class Application < Rails::Application
  config.middleware.use Rack::SPARQL::ContentNegotiation
end

Adding SPARQL content negotiation to a Rackup application

#!/usr/bin/env rackup
require 'rack/sparql'

repository = RDF::Repository.new do |graph|
  graph << [RDF::Node.new, RDF::DC.title, "Hello, world!"]
end
results = SPARQL.execute("SELECT * WHERE { ?s ?p ?o }", repository)

use Rack::SPARQL::ContentNegotiation
run lambda { |env| [200, {}, results] }

Adding SPARQL content negotiation to a classic Sinatra application

# Sinatra example
#
# Call as http://localhost:4567/sparql?query=uri,
# where `uri` is the URI of a SPARQL query, or
# a URI-escaped SPARQL query, for example:
#   http://localhost:4567/?query=SELECT%20?s%20?p%20?o%20WHERE%20%7B?s%20?p%20?o%7D
require 'sinatra'
require 'sinatra/sparql'
require 'uri'

get '/' do
settings.sparql_options.replace(:standard_prefixes => true)
  repository = RDF::Repository.new do |graph|
    graph << [RDF::Node.new, RDF::DC.title, "Hello, world!"]
  end
  if params["query"]
    query = params["query"].to_s.match(/^http:/) ? RDF::Util::File.open_file(params["query"]) : ::URI.decode(params["query"].to_s)
    SPARQL.execute(query, repository)
  else
    settings.sparql_options.merge!(:prefixes => {
      :ssd => "http://www.w3.org/ns/sparql-service-description#",
      :void => "http://rdfs.org/ns/void#"
    })
    service_description(:repo => repository)
  end
end

Documentation

Full documentation available on Rubydoc.info

Principle Classes

  • {SPARQL}
    • {SPARQL::Algebra}
      • {SPARQL::Algebra::Expression}
      • {SPARQL::Algebra::Query}
      • {SPARQL::Algebra::Operator}
    • {SPARQL::Grammar}
      • {SPARQL::Grammar::Parser}
      • {SPARQL::Grammar::Lexer}
  • {Sinatra::SPARQL}
  • {Rack::SPARQL}
    • {Rack::SPARQL::ContentNegotiation}

Dependencies

  • Ruby (>= 1.9) or (>= 1.8.1 with Backports)
  • RDF.rb (>= 0.3.5)
  • SPARQL::Client (>= 0.0.11)
  • SXP (>= 0.0.15)
  • Builder (>= 3.0.0)
  • JSON (>= 1.5.1)
  • Soft dependency on Linked Data (>= 0.3.5)
  • Soft dependency on Nokogiri (>= 1.3.3) Falls back to REXML for XML parsing Builder for XML serializing. Nokogiri is much more efficient
  • Soft dependency on Equivalent XML (>= 0.2.9) Equivalent XML performs more efficient comparisons of XML Literals when Nokogiri is included
  • Soft dependency on Rack (>= 1.3.2)
  • Soft dependency on Sinatra (>= 1.4.1)

Installation

The recommended installation method is via RubyGems. To install the latest official release of the SPARQL gem, do:

% [sudo] gem install sparql

Download

To get a local working copy of the development repository, do:

% git clone git://github.com/ruby-rdf/sparql.git

Mailing List

Authors

Contributing

  • Do your best to adhere to the existing coding conventions and idioms.
  • Don't use hard tabs, and don't leave trailing whitespace on any line.
  • Do document every method you add using YARD annotations. Read the tutorial or just look at the existing code for examples.
  • Don't touch the .gemspec, VERSION or AUTHORS files. If you need to change them, do so on your private branch only.
  • Do feel free to add yourself to the CREDITS file and the corresponding list in the the README. Alphabetical order applies.
  • Do note that in order for us to merge any non-trivial changes (as a rule of thumb, additions larger than about 15 lines of code), we need an explicit public domain dedication on record from you.

License

This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying {file:UNLICENSE} file.

Something went wrong with that request. Please try again.