HTTP Bindings for the Stardog RDF database.
gem install stardog-rb
require 'stardog'
include Stardog
You can use the stardog function to open a connection. It accepts the endpoint URL as well as a hash of options: user, password, reasoning, etc...
sd = stardog("http://localhost:5822/",
:user => "admin",
:password => "admin",
:reasoning => "QL")
sd.create_db(db_name)
sd.drop_db(db_name)
Triples can be added from a text string, a file system path or a remote URL:
triples = ['<http://localhost/publications/articles/Journal1/1940/Article2>',
'<http://purl.org/dc/elements/1.1/subject>',
'"A very interesting subject"^^<http://www.w3.org/2001/XMLSchema#string>.'].join(' ')
sd.add(db_name, triples)
path = File.join(File.dirname(__FILE__), "data", "api_tests.nt")
sd.add(db_name, path)
url = "http://dbpedia.org/data/The_Lord_of_the_Rings"
db.add(db_name, url, nil, "application/rdf+xml")
Removing triples can be accomplished with the symmetrical remove function:
db.remove(@db_name, url, nil, "application/rdf+xml")
Triples can be inserted inside a named graph passing a third argument to the add and remove methods.
db.add(db_name, a_triple2,"my:graph")
All operations will run inside a single Stardog transaction.
Transactions can be executed using the with_transaction helper method that will take care of committing if the transaction is successful or rolling back the transaction if an exception is raised:
result = sd.with_transaction(db_name) do |txID|
sd.add_in_transaction(db_name, txID, a_triple1)
sd.add_in_transaction(db_name, txID, a_triple2)
end
The methods add_in_transaction and remove_in_transaction have the same interface as the add and remove functions but also accepting a transaction ID. The previous code is analogous to this version using the begin and commit methods:
result = begin
txID = begin(db_name)
sd.add_in_transaction(db_name, txID, a_triple1)
sd.add_in_transaction(db_name, txID, a_triple2)
commit(db_name, txID)
true
rescue Exception => ex
rollback(db_name, txID)
false
end
Queries can be issued using the query method. Results will be returned as a LinkedJSON that can be processed as a regular Hash.
results = conn.query(db_name, "select ?g ?s where { graph ?g { ?s ?p ?o } }")
results.body["head"]["vars"] # > ["g","s"]
results.body["results"]["bindings"].inject({}) do |a,b|
a[b["g"]["value"]] = b["s"]["value"]; a
end # > { graph_uri => uri }
Options limit, offset and base_uri can be passed to the query method as a hash of options.
Queries can be run inside a transaction using the query_in_transaction variation of the query method:
db.with_transaction(db_name) do |txID|
results = query_in_transaction(db_name, txID, query)
end
To enable reasoning in queries, the reasoning option with the right reasoning level (QL, RDFS, EL...) must be provided. Inferred results will be obtained when queries are issued.
For example, for the database:
@prefix : <http://example.com/test/> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
:Company a rdfs:Class .
:Organization a rdfs:Class .
:Company rdfs:subClassOf :Organization .
:clark_and_parsia rdf:type :Company .
The following query will not return any result:
@conn = stardog("http://localhost:5822/", :user => "admin", :password => "admin")
results = @conn.query(@db_name, "select ?c where { ?c a <http://example.com/test/Organization> }")
data = results.body["results"]["bindings"]
expect(data.length).to be_eql(0)
After setting the connection level in the connection string, inferred results will be returned
@conn_reasoning = stardog("http://localhost:5822/", :user => "admin", :password => "admin", :reasoning => "QL")
results = @conn_reasoning.query(@db_name, "select ?c where { ?c a <http://example.com/test/Organization> }")
data = results.body["results"]["bindings"]
expect(data.length).to be_eql(1) # > c => ':clark_and_parsia'
Consistency of the database can be checked using the consistent? method in a reasoning enabled connection:
@conn_reasoning.consistent?(@db_name) # > true
Refer to Stardog's documentation about reasoning (http://stardog.com/docs/owl2/#reasoning) for more details about TBox extraction, different reasoning levels, etc.
Antonio Garrote (antoniogarrote@gmail.com)
This implementation is a work in progress. Some functionality has not been yet wrapped.
You can turn on debugging by setting the STARDOG_RB_DEBUG environment variable to true.
Specs can be run using RSpec.