Examples
This chapters shows some real examples of usage of the Tracker SPARQL Library.
Querying the Store
First, a TrackerSparqlConnection object must be acquired with tracker_sparql_connection_new, tracker_sparql_connection_bus_new or tracker_sparql_connection_remote_new.
Then, a query can be launched either synchronously (tracker_sparql_connection_query) or asynchronously (tracker_sparql_connection_query_async). If launched asynchronously, the results of the query can be obtained with tracker_sparql_connection_query_finish.
If the query was successful, a TrackerSparqlCursor will be available. You can now iterate the results of the query both synchronously (with tracker_sparql_cursor_next) or asynchronously (with tracker_sparql_cursor_next_async and tracker_sparql_cursor_next_finish).
The tracker_sparql_connection_query_statement function 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.
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.
The following program shows how Read-Only queries can be done to the store in a synchronous way:
#include <libtracker-sparql/tracker-sparql.h>
int main (int argc, const char **argv)
{
GError *error = NULL;
TrackerSparqlConnection *connection;
TrackerSparqlCursor *cursor;
TrackerSparqlStatement *stmt;
const gchar *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject }";
connection = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker3.Miner.Files", NULL, NULL, &error);
if (!connection) {
g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
error ? error->message : "unknown error");
g_clear_error (&error);
return 1;
}
/* Make a synchronous query to the store */
cursor = tracker_sparql_connection_query (connection,
query,
NULL,
&error);
if (error) {
/* Some error happened performing the query, not good */
g_printerr ("Couldn't query the Tracker Store: '%s'",
error->message);
g_clear_error (&error);
return 1;
}
/* Check results... */
if (!cursor) {
g_print ("No results found :-/\n");
} else {
gint i = 0;
/* 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);
g_object_unref (cursor);
}
/* Prepare the statement with tracker_sparql_connection_query_statement */
stmt = tracker_sparql_connection_query_statement (connection,
query,
NULL,
&error);
if (error) {
/* Some error happened performing the query, not good */
g_printerr ("Couldn't query the Tracker Store: '%s'",
error->message);
g_clear_error (&error);
return 1;
}
/* Executes the SPARQL query with the currently bound values and get new cursor */
cursor = tracker_sparql_statement_execute (stmt, NULL, &error);
/* Check results... */
if (!cursor) {
g_print ("No results found :-/\n");
} else {
gint i = 0;
/* 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);
g_object_unref (cursor);
}
g_object_unref (connection);
return 0;
}
Updating the store
In order to perform updates in the store, a new writable TrackerSparqlConnection object must be acquired with tracker_sparql_connection_new.
Once a proper connection object has been acquired, the update can be launched either synchronously (tracker_sparql_connection_update) or asynchronously (tracker_sparql_connection_update_async). If launched asynchronously, the result of the operation can be obtained with tracker_sparql_connection_update_finish.
Once you no longer need the connection, remember to call tracker_sparql_connection_close on the TrackerSparqlConnection.
The following program shows how a synchronous update can be done to the store:
#include <libtracker-sparql/tracker-sparql.h>
int main (int argc, const char **argv)
{
GError *error = NULL;
TrackerSparqlConnection *connection;
const gchar *query =
"INSERT { "
" _:tag a nao:Tag ; "
" nao:prefLabel 'mylabel' . "
"} WHERE { "
" OPTIONAL { "
" ?tag a nao:Tag ; "
" nao:prefLabel 'mylabel' "
" } . "
"FILTER (!bound(?tag)) "
"}";
connection = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker3.Miner.Files", NULL, NULL, &error);
if (error) {
g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
error->message);
g_clear_error (&error);
return 1;
}
/* Run a synchronous update query */
tracker_sparql_connection_update (connection,
query,
NULL,
&error);
if (error) {
/* Some error happened performing the query, not good */
g_printerr ("Couldn't update the Tracker store: %s",
error->message);
g_clear_error (&error);
g_object_unref (connection);
return 1;
}
g_object_unref (connection);
return 0;
}
Updating the store with blank nodes
The majority of the work here is already described in the previous example where we talk about how to write the store.
The difference with this example is that sometimes you want to insert data and have the URNs returned which were created to avoid re-querying for them. This is done using the tracker_sparql_connection_update_blank function (or asynchronously with tracker_sparql_connection_update_blank_async). If launched asynchronously, the result of the operation can be obtained with tracker_sparql_connection_update_blank_finish]
The _:foo
in the example is how a blank node is
represented in SPARQL. The foo
part is used to generate the
unique ID that is used for the new URN. It is also used in the
GVariant
that is returned. In the example below, we are creating
a new blank node called foo
for every class that exists.
The format of the GVariant
(in D-Bus terms) is aaa{ss}
(an
array of an array of dictionaries). This is rather complex but
for a good reason. The first array represents each INSERT that
may exist in the SPARQL. The second array represents each new
node for a given WHERE clause (the example below illustrates
this), you need this to differentiate between two INSERT
statments like the one below in the same SPARQL sent to the
store. Last, we have a final array to represent each new node's
name (in this case foo
) and the actual URN which was
created. For most updates the first two outer arrays will only
have one item in them.
The following program shows how a synchronous blank node update can be done to the store:
#include <libtracker-sparql/tracker-sparql.h>
int main (int argc, const char **argv)
{
GError *error = NULL;
GVariant *v;
TrackerSparqlConnection *connection;
const gchar *query =
"INSERT { _:foo a nie:InformationElement } WHERE { ?x a rdfs:Class }";
connection = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker1", NULL, NULL, &error);
if (error) {
g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
error->message);
g_clear_error (&error);
return 1;
}
/* Run a synchronous blank node update query */
v = tracker_sparql_connection_update_blank (connection,
query,
NULL,
&error);
if (error) {
/* Some error happened performing the query, not good */
g_printerr ("Couldn't update the Tracker store: %s",
error->message);
g_clear_error (&error);
g_object_unref (connection);
return 1;
}
if (!v) {
g_print ("No results were returned\n");
} else {
GVariantIter iter1, *iter2, *iter3;
const gchar *node;
const gchar *urn;
g_print ("Results:\n");
g_variant_iter_init (&iter1, v);
while (g_variant_iter_loop (&iter1, "aa{ss}", &iter2)) { /* aa{ss} */
while (g_variant_iter_loop (iter2, "a{ss}", &iter3)) { /* a{ss} */
while (g_variant_iter_loop (iter3, "{ss}", &node, &urn)) { /* {ss} */
g_print (" Node:'%s', URN:'%s'\n", node, urn);
}
}
}
g_variant_unref (v);
}
g_object_unref (connection);
return 0;
}
The results of the search are