Querying a remote endpoint

All SPARQL queries happen through a TrackerSparqlConnection, often these connections represent a remote endpoints maintained by another process or server.

This example demonstrates the use of these connections on a remote endpoint. Concretely creating a D-Bus TrackerSparqlConnection, creating a prepared statement from a SPARQL query string, executing the query, and obtaining the query results from the cursor.

The tracker_sparql_connection_query_statement() method can be used to obtain a TrackerSparqlStatement object holding a prepared SPARQL query that can then be executed with tracker_sparql_statement_execute(). The query string can contain ~name placeholders which can be replaced with arbitrary values before query execution with tracker_sparql_statement_bind_string() and similar functions. This allows parsing the query string only once and to execute it multiple times with different parameters with potentially significant performance gains.

Multiple functions offer asynchronous variants, so the application main loop is not blocked while these operations are executed.

Once you end up with the query, remember to call tracker_sparql_cursor_close(). The same applies to tracker_sparql_connection_close() when no longer needed.

In C:

#include <tinysparql.h>

#define REMOTE_NAME "org.freedesktop.Tracker3.Miner.Files"

int main (int argc, const char **argv)
{
  g_autoptr (GError) error = NULL;
  g_autoptr (TrackerSparqlConnection) connection = NULL;
  g_autoptr (TrackerSparqlCursor) cursor = NULL;
  g_autoptr (TrackerSparqlStatement) stmt = NULL;
  const char *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject ; nfo:fileName ~name }";
  const char *name = NULL;
  int i = 0;

  connection = tracker_sparql_connection_bus_new (REMOTE_NAME, NULL, NULL, &error);
  if (!connection) {
    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
                error ? error->message : "unknown error");
    return 1;
  }

  /* Create a prepared statement */
  stmt = tracker_sparql_connection_query_statement (connection,
                                                    query,
                                                    NULL,
                                                    &error);

  if (!stmt) {
    g_printerr ("Couldn't create a prepared statement: '%s'",
                error->message);
    return 1;
  }

  /* Bind a value to the query variables */
  name = argv[1] ? argv[1] : "";
  tracker_sparql_statement_bind_string (stmt, "name", name);

  /* Executes the SPARQL query with the currently bound values and get new cursor */
  cursor = tracker_sparql_statement_execute (stmt, NULL, &error);
  if (!cursor) {
    g_printerr ("Couldn't execute query: '%s'",
                error->message);
    return 1;
  }

  /* Iterate synchronously the results */
  while (tracker_sparql_cursor_next (cursor, NULL, &error)) {
    g_print ("Result [%d]: %s\n",
             i++,
             tracker_sparql_cursor_get_string (cursor, 0, NULL));
  }

  g_print ("A total of '%d' results were found\n", i);

  tracker_sparql_cursor_close (cursor);

  tracker_sparql_connection_close (connection);

  return 0;
}

In Python:

#!/usr/bin/python3

import gi, sys
from gi.repository import GLib, Gio, Tsparql

try:
    connection = Tsparql.SparqlConnection.bus_new(
        'org.freedesktop.Tracker3.Miner.Files',
        None, None)

    stmt = connection.query_statement (
        'SELECT DISTINCT nie:url(?u) WHERE { ' +
        '  ?u a nfo:FileDataObject ; ' +
        '     nfo:fileName ~name ' +
        '}', None)

    stmt.bind_string('name', sys.argv[1])

    cursor = stmt.execute()
    i = 0;

    while cursor.next():
        i += 1
        print('Result {0}: {1}'.format(i, cursor.get_string(0)[0]))

    print('A total of {0} results were found\n'.format(i))

    cursor.close()
    connection.close()

except Exception as e:
    print('Error: {0}'.format(e))
    sys.exit(-1)

In Javascript:

#!/usr/bin/gjs

const { GLib, Gio, Tsparql } = imports.gi

try {
    let connection = Tsparql.SparqlConnection.bus_new(
        'org.freedesktop.Tracker3.Miner.Files',
        null, null);

    let stmt = connection.query_statement (
        'SELECT DISTINCT nie:url(?u) WHERE { ' +
        '  ?u a nfo:FileDataObject ; ' +
        '     nfo:fileName ~name ' +
        '}', null);

    stmt.bind_string('name', ARGV[0]);

    let cursor = stmt.execute(null);
    let i = 0;

    while (cursor.next(null)) {
        i++;
        print(`Result ${i}: ${cursor.get_string(0)[0]}`);
    }

    print(`A total of ${i} results were found`);

    cursor.close();
    connection.close();
} catch (e) {
    printerr(`Error: ${e.message}`)
}

Creating a private database

Applications may create private RDF triple stores via the tracker_sparql_connection_new() constructor.

This example demonstrates the creation of a private store, for simplicity the example uses the builtin Nepomuk ontology, but the data structures may be defined by the application, see the documentation on creating custom ontologies for more information about this.

The example also demonstrates the use of TrackerResource and TrackerBatch for insertion of RDF data. It is also possible to use TrackerSparqlStatement for updates through the tracker_batch_add_statement() methods, or plain SPARQL strings through tracker_batch_add_sparql().

Multiple functions offer asynchronous variants, so the application main loop is not blocked while these operations are executed.

Once you no longer need the connection, remember to call tracker_sparql_connection_close().

In C:

#include <tinysparql.h>

int main (int argc, const char **argv)
{
  g_autoptr (GError) error = NULL;
  g_autoptr (TrackerSparqlConnection) connection = NULL;
  g_autoptr (TrackerResource) resource = NULL;
  g_autoptr (GFile) ontology = NULL;

  /* Create a private SPARQL store */
  ontology = tracker_sparql_get_ontology_nepomuk ();
  connection = tracker_sparql_connection_new (TRACKER_SPARQL_CONNECTION_FLAGS_NONE,
                          NULL, /* Database location, NULL creates it in-memory */
                          ontology, /* Ontology location */
                          NULL,
                          &error);
  if (connection) {
    g_printerr ("Couldn't create a Tracker store: %s",
                error->message);
    return 1;
  }

  /* Create a resource containing RDF data */
  resource = tracker_resource_new (NULL);
  tracker_resource_set_uri (resource, "rdf:type", "nmm:MusicPiece");

  /* Create a batch, and add the resource to it */
  batch = tracker_sparql_connection_create_batch (connection);
  tracker_batch_add_resource (batch, NULL, resource);

  /* Execute the batch to insert the data */
  if (!tracker_batch_execute (batch, NULL, &error)) {
    g_printerr ("Couldn't insert batch of resources: %s",
                error->message);
    return 1;
  }

  tracker_sparql_connection_close (connection);

  return 0;
}

In Python:

#!/usr/bin/python3

import gi, sys
from gi.repository import GLib, Gio, Tsparql

try:
    connection = Tsparql.SparqlConnection.new(
        Tsparql.SparqlConnectionFlags.NONE,
        None, # Database location, None creates it in-memory
        Tsparql.sparql_get_ontology_nepomuk(), # Ontology location
        None)

    # Create a resource containing RDF data
    resource = Tsparql.Resource.new(None)
    resource.set_uri('rdf:type', 'nmm:MusicPiece')

    # Create a batch, and add the resource to it
    batch = connection.create_batch()
    batch.add_resource(None, resource)

    # Execute the batch to insert the data
    batch.execute()

    connection.close()

except Exception as e:
    print('Error: {0}'.format(e))
    sys.exit(-1)

In Javascript:

#!/usr/bin/gjs

const { GLib, Gio, Tsparql } = imports.gi

try {
    let connection = Tsparql.SparqlConnection.new(
        Tsparql.SparqlConnectionFlags.NONE,
        null, // Database location, None creates it in-memory
        Tsparql.sparql_get_ontology_nepomuk(), // Ontology location
        null);

    // Create a resource containing RDF data
    let resource = Tsparql.Resource.new(null)
    resource.set_uri('rdf:type', 'nmm:MusicPiece')

    // Create a batch, and add the resource to it
    let batch = connection.create_batch()
    batch.add_resource(null, resource)

    // Execute the batch to insert the data
    batch.execute(null)

    connection.close();
} catch (e) {
    printerr(`Error: ${e.message}`)
}

Creating a SPARQL endpoint

For some applications and services, it might be desirable to export a RDF triple store as an endpoint. Making it possible for other applications to query the data they hold.

This example demonstrates the use of TrackerEndpoint subclasses, concretely the creation of a D-Bus endpoint, that other applications may query e.g. through a connection created with tracker_sparql_connection_bus_new().

In C:

#include <tinysparql.h>

int main (int argc, const char **argv)
{
  g_autoptr (GError) error = NULL;
  g_autoptr (TrackerSparqlConnection) connection = NULL;
  g_autoptr (GFile) ontology = NULL;
  g_autoptr (GMainLoop) main_loop = NULL;

  /* Create a SPARQL store */
  ontology = tracker_sparql_get_ontology_nepomuk ();
  connection = tracker_sparql_connection_new (TRACKER_SPARQL_CONNECTION_FLAGS_NONE,
                          NULL, /* Database location, NULL creates it in-memory */
                          ontology, /* Ontology location */
                          NULL,
                          &error);
  if (connection) {
    g_printerr ("Couldn't create a Tracker store: %s",
                error->message);
    return 1;
  }

  /* Make the connection available via D-Bus, other applications would be
   * able to make connections to this application's bus name
   */
  endpoint = tracker_endpoint_dbus_new (connection, NULL, NULL, NULL, &error);
  if (!endpoint) {
    g_printerr ("Couldn't create D-Bus endpoint: %s",
                error->message);
    return 1;
  }

  main_loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (main_loop);

  return 0;
}

In Python:

#!/usr/bin/python3

import gi, sys
from gi.repository import GLib, Gio, Tsparql

try:
    connection = Tsparql.SparqlConnection.new(
        Tsparql.SparqlConnectionFlags.NONE,
        None, # Database location, None creates it in-memory
        Tsparql.sparql_get_ontology_nepomuk(), # Ontology location
        None)

    bus = Gio.bus_get_sync(Gio.BusType.SESSION, None)

    endpoint = Tsparql.EndpointDBus.new(
        connection, bus, None, None)

    loop = GLib.MainLoop.new(None, False)
    loop.run()

    connection.close()

except Exception as e:
    print('Error: {0}'.format(e))
    sys.exit(-1)

In Javascript:

#!/usr/bin/gjs

const { GLib, Gio, Tsparql } = imports.gi

try {
    let connection = Tsparql.SparqlConnection.new(
        Tsparql.SparqlConnectionFlags.NONE,
        null, // Database location, None creates it in-memory
        Tsparql.sparql_get_ontology_nepomuk(), // Ontology location
        null);

    let bus = Gio.bus_get_sync(Gio.BusType.SESSION, null)

    let endpoint = Tsparql.EndpointDBus.new(
        connection, bus, null, null);

    let loop = GLib.MainLoop.new(null, false);
    loop.run();

    connection.close();
} catch (e) {
    printerr(`Error: ${e.message}`)
}

Receiving notification on changes

As an additional feature over SPARQL endpoints, TinySPARQL allows for users of private and D-Bus SPARQL connections to receive notifications on changes of certain RDF classes (Those with the nrl:notify property, like nmm:MusicPiece).

This example demonstrates the use of TrackerNotifier to receive notifications on database updates.

In C:

#include <tinysparql.h>

#define REMOTE_NAME "org.freedesktop.Tracker3.Miner.Files"

void on_events (TrackerNotifier *notifier,
                const char      *service,
                const char      *graph,
                GPtrArray       *events,
                gpointer         user_data)
{
  int i;

  for (i = 0; i < events->len; i++) {
    TrackerNotifierEvent *event = g_ptr_array_index (events, i);

    g_print ("Event %d on %s\n",
             tracker_notifier_event_get_event_type (event),
             tracker_notifier_event_get_urn (event));
  }
}

int main (int   argc,
          char *argv[])
{
  g_autoptr (GError) error = NULL;
  g_autoptr (TrackerSparqlConnection) connection = NULL;
  g_autoptr (TrackerNotifier) notifier = NULL;
  g_autoptr (GMainLoop) main_loop = NULL;

  /* Create connection to remote service */
  connection = tracker_sparql_connection_bus_new (REMOTE_NAME, NULL, NULL, &error);
  if (!connection) {
    g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
                error ? error->message : "unknown error");
    return 1;
  }

  /* Create notifier, and connect to its events signal */
  notifier = tracker_sparql_connection_create_notifier (connection);
  g_signal_connect (notifier, "events", G_CALLBACK (on_events), NULL);

  main_loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (main_loop);

  tracker_sparql_connection_close (connection);

  return 0;
}

In Python:

#!/usr/bin/python3

import gi, sys
from gi.repository import GLib, Gio, Tsparql

def callback(service, graph, events):
    for event in events:
        print('Event {0} on {1}\n'.format(
            event.get_event_type(), event.get_urn()))

try:
    connection = Tsparql.SparqlConnection.bus_new(
        'org.freedesktop.Tracker3.Miner.Files',
        None, None)

    notifier = connection.create_notifier()
    notifier.connect('events', callback)

    loop = GLib.MainLoop.new(None, False)
    loop.run()

    connection.close()

except Exception as e:
    print('Error: {0}'.format(e))
    sys.exit(-1)

In Javascript:

#!/usr/bin/gjs

const { GLib, Gio, Tsparql } = imports.gi

try {
    let connection = Tsparql.SparqlConnection.bus_new(
        'org.freedesktop.Tracker3.Miner.Files',
        null, null);

    let notifier = connection.create_notifier();
    notifier.connect('events', (service, graph, events) => {
        for (let event in events)
            print (`Event ${event.get_event_type()} on ${event.get_urn()}`);
    });

    let loop = GLib.MainLoop.new(null, false);
    loop.run();

    connection.close();
} catch (e) {
    printerr(`Error: ${e.message}`)
}