node package manager


Simple SPARQL HTTP Client library for Node.js

Getting Started


npm install sparql


sparql = require 'sparql'
client = new sparql.Client ''
client.query 'select * where { ?s ?p ?o } limit 100', (err, res) ->
  console.log res

The result of calling the query() function will be a raw object conforming to the SPARQL-JSON[1] results format.

Core API


Low level function. Returns the complete SPARQL-JSON results object.

client.query 'select * where {?s ?p ?o} limit 10', (err, res) ->
  console.log row.s for row in res.results.bindings

Convenience Query Methods


Convenience method to get to the rows directly. Builds on top of sparql.query, like most of the other query methods.

client.rows 'select * where {?s ?p ?o} limit 10', (err, res) ->
  console.log row.s for row in res


Convenience method that only returns the first row in the result set

client.row 'select * where {?s ?p ?o} limit 10', (err, res) ->
  console.log res.s


Convenience method that returns an array of with the first value of each row

client.col 'select distinct ?name where {?s foaf:name ?name} limit 10', (err, res) ->
  console.log( rdf_value.value ) for rdf_value in res

What's with the rdf_value.value part? Read the SPARQL-JSON results format specification page.


Convenience method that returns only the first binding of the first row or NULL

client.col 'select ?name where {?s foaf:name ?name} limit 1', (err, res) ->
  console.log res

Convenience Update Methods

There are a bunch of higher level methods that generate SPARQL for you. I am providing a small number of such methods, as I don't want this library to grow into something like Active Record.

Writing SPARQL by hand is highly encouraged.


Provide an abstraction atop a simple 'entity oriented' operation that is not so simple when you are working with SPARQL.

Imagine you want to do something like this, conceptually speaking: = 'Aldo'

You can get that with one simple call to the API

client.set '<urn:test:graph>', '<urn:test:aldo>', '<urn:test:name>', '"Aldo"', no, (err, res) ->
  console.log 'Aldo is now named Aldo, hooray!' 

Not so simple? Well, compare that to the SPARQL Update statement that gets generated under the covers:

modify <urn:test:graph> 
  delete { <urn:test:aldo> <urn:test:name> ?x } 
  insert { <urn:test:aldo> <urn:test:name> "Aldo" } 
  where { optional{ <urn:test:aldo> <urn:test:name> ?x } }

Notice that, if <urn:test:aldo> had a previous <urn:test:name>, it will be replaced. If it doesn't, then a new triple will be inserted.

You can also delete a value by setting it to null ( effectively removing one or more triples )

client.set '<urn:test:graph>', '<urn:test:aldo>', '<urn:test:name>', null, no, (err, res) ->
  console.log 'Aldo went back to anonimity'

In this case, the generated SPARQL is:

delete from <urn:test:graph>
  { <urn:test:aldo> <urn:test:name> ?x }
  where { <urn:test:aldo> <urn:test:name> ?x }

The 5th parameter is a boolean flag indicating whether the triple patterns should be inverted ( useful for when you only have the reversed predicate )


One Subject, several pairs Predicate-Object

Let's group some attributes of an user

attributes = 
	'<urn:test:username>' : 'haj'
	'<urn:test:password>' : '123'
	'<urn:test:name>' : 'Herman'

And we invoke mset

client.mset  '<urn:test:graph>', <urn:test:haj>', attributes, (err, res) ->
	if err?
		console.log 'Success'
		console.log 'Error: ' + err

The SPARQL query generated is:

INSERT INTO <urn:test:graph>
	{ <urn:test:haj> 	<urn:test:username> 	'Haj';
						<urn:test:password>		'123';
						<urn:test:name>			'Herman'. }


Test Dependencies

You must have OpenLink Virtuoso >= 6.1.2 installed and virtuoso, isql in your path.

Also, maybe you have to set Virtuoso to allow INSERT and DELETE to be done via sparql:

$ isql

You must also have expresso npm install expresso

Running the Tests

(Coming Soon)