pdlug / stardog-ruby

A basic ruby client for the Stardog RDF database

Stardog - A Simple Ruby Client for the Stardog RDF Database

This is a very basic wrapper around the Stardog HTTP (REST) API providing basic support for adding/removing/clearing data in a database and querying using SPARQL.

Getting started

1. Install Stardog and read the Quick start guide

2. Create a database for testing (we'll use rubytest for the examples below):

   stardog-admin db create -n rubytest -t D -u admin -p admin
   

3. Connect with ruby

   require 'stardog'
   db = Stardog::Server.new(url: 'http://127.0.0.1:5822')
     .db('rubytest', username: 'admin', password: 'admin')
   

4. Load some data

   rdf_data = File.read(File.expand_path('./test.turtle', File.dirname(__FILE__)))
   db.transaction do
     add(rdf_data, Stardog::Format::TURTLE)
     commit
   end
   

5. Try a few queries, query results are returned as an Enumerable of RDF::Query::Solution objects.

   # Find each distinct subject in the database
   db.query('SELECT DISTINCT ?s WHERE { ?s ?p ?o } LIMIT 10').each do |solution|
     puts solution[:s]
   end
   

   # Find out who created Stardog
   db.query(%Q{
     PREFIX dc: <http://purl.org/dc/elements/1.1/>
   
     SELECT ?name
     WHERE { 
       <http://stardog.com/> dc:creator ?creator .
       ?creator dc:title ?name .
     }
   }).first[:name]
   

6. Drop the database

   stardog-admin db drop rubytest
   

Configuring

The Stardog::Server object providers the base wrapper around connections to the server and uses Faraday to enable support for multiple HTTP backends. Any of the HTTP client adapters supported by Faraday can be used by specifying them in the :adapter parameter (e.g. Stardog::Server.new(url: ..., adapter: :typhoeus)). By default the :net_http adapter is used since it is built into ruby and requires no external dependencies, please see the note below for some of the limitations with this.

IMPORTANT NOTE: Stardog requires that the SD-* headers be specified with the proper capitalization, this does not work with the default ruby :net_http adapter. The ruby net/http library normalizes all headers by downcasing them then introducing mixed caps, this turns headers like SD-Connection-String into Sd-Connection-String and Stardog disgards it (which is wrong, HTTP headers are case insensitive per the spec). For now the only solution is to use an adapter that does not mess with the headers this way, I am successfully using both :excon and :typheous but others may work as well.

See Also

• Stardog Documentation - the Stardog docs are awesome, read them.

TODO

• Comprehensive error handling - not all HTTP errors are currently handled, more detailed error reporting is also possible by examining the SD-Error-Code header if present.
• Better SPARQL query result wrapper - the basic Enumerable of RDF::Query::Solution will be replaced with a more robust wrapper for results that will enable more convenience methods.