TrackerSparqlConnection: Tracker SPARQL Library Reference Manual

TrackerSparqlConnection

TrackerSparqlConnection — Connection to SPARQL triple store

Stability Level

Stable, unless otherwise indicated

Functions

TrackerSparqlConnection *	tracker_sparql_connection_new ()
void	tracker_sparql_connection_new_async ()
TrackerSparqlConnection *	tracker_sparql_connection_new_finish ()
TrackerSparqlConnection *	tracker_sparql_connection_remote_new ()
TrackerSparqlConnection *	tracker_sparql_connection_bus_new ()
TrackerSparqlCursor *	tracker_sparql_connection_query ()
void	tracker_sparql_connection_query_async ()
TrackerSparqlCursor *	tracker_sparql_connection_query_finish ()
TrackerSparqlStatement *	tracker_sparql_connection_query_statement ()
void	tracker_sparql_connection_update ()
void	tracker_sparql_connection_update_async ()
void	tracker_sparql_connection_update_finish ()
void	tracker_sparql_connection_update_array_async ()
gboolean	tracker_sparql_connection_update_array_finish ()
GVariant *	tracker_sparql_connection_update_blank ()
void	tracker_sparql_connection_update_blank_async ()
GVariant *	tracker_sparql_connection_update_blank_finish ()
gboolean	tracker_sparql_connection_update_resource ()
void	tracker_sparql_connection_update_resource_async ()
gboolean	tracker_sparql_connection_update_resource_finish ()
TrackerNamespaceManager *	tracker_sparql_connection_get_namespace_manager ()
TrackerNotifier *	tracker_sparql_connection_create_notifier ()
TrackerBatch *	tracker_sparql_connection_create_batch ()
void	tracker_sparql_connection_close ()
void	tracker_sparql_connection_close_async ()
gboolean	tracker_sparql_connection_close_finish ()

Types and Values

	TrackerSparqlConnection
enum	TrackerSparqlConnectionFlags

Object Hierarchy

    GFlags
    ╰── TrackerSparqlConnectionFlags
    GObject
    ╰── TrackerSparqlConnection

Includes

#include <tracker-sparql.h>

Description

TrackerSparqlConnection is an object that represents a connection to a SPARQL triple store. This store may be local and private (see tracker_sparql_connection_new()), or it may be a remote connection to a public endpoint (See tracker_sparql_connection_bus_new() and tracker_sparql_connection_remote_new()).

A TrackerSparqlConnection is private to the calling process, it can be exposed publicly via a TrackerEndpoint, see tracker_endpoint_dbus_new().

Updates on a connection are performed via the tracker_sparql_connection_update() family of calls. tracker_sparql_connection_update_array() may be used for batched updates. All functions have asynchronous variants.

Queries on a connection are performed via tracker_sparql_connection_query() and tracker_sparql_connection_query_statement(). The first call receives a query string and returns a TrackerSparqlCursor to iterate the results. The second call returns a TrackerSparqlStatement object that may be reused for repeatable queries with variable parameters. tracker_sparql_statement_execute() will returns a TrackerSparqlCursor.

Depending on the ontology definition, TrackerSparqlConnection may emit notifications whenever changes happen in the stored data. These notifications can be processed via a TrackerNotifier obtained with tracker_sparql_connection_create_notifier().

After use, a TrackerSparqlConnection should be closed. See tracker_sparql_connection_close() and tracker_sparql_connection_close_async().

Functions

tracker_sparql_connection_new ()

TrackerSparqlConnection *
tracker_sparql_connection_new (TrackerSparqlConnectionFlags flags,
                               GFile *store,
                               GFile *ontology,
                               GCancellable *cancellable,
                               GError **error);

Creates or opens a database.

This method should only be used for databases owned by the current process. To connect to databases managed by other processes, use tracker_sparql_connection_bus_new().

If store is NULL, the database will be created in memory.

The ontologies parameter must point to a location containing suitable .ontology files in Turtle format. These control the database schema that is used. You can use the default Nepomuk ontologies by calling tracker_sparql_get_ontology_nepomuk().

If you open an existing database using a different ontology to the one it was created with, Tracker will attempt to migrate the existing data to the new schema. This may raise an error. In particular, not all migrations are possible without causing data loss and Tracker will refuse to delete data during a migration.

You can also pass NULL for ontologies to mean "use the ontologies that the database was created with". This will fail if the database doesn't already exist.

Parameters

flags	values from TrackerSparqlConnectionFlags
store	the directory that contains the database as a GFile, or `NULL`.	[nullable]
ontology	the directory that contains the database schemas as a GFile, or `NULL`.	[nullable]
cancellable	a GCancellable, or `NULL`.	[nullable]
error	pointer to a GError

Returns

a new TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

[transfer full]

Since: 3.0

tracker_sparql_connection_new_async ()

void
tracker_sparql_connection_new_async (TrackerSparqlConnectionFlags flags,
                                     GFile *store,
                                     GFile *ontology,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Asynchronous version of tracker_sparql_connection_new().

Parameters

flags	values from TrackerSparqlConnectionFlags
store	the directory that contains the database as a GFile, or `NULL`.	[nullable]
ontology	the directory that contains the database schemas as a GFile, or `NULL`.	[nullable]
cancellable	a GCancellable, or `NULL`.	[nullable]
callback	the GAsyncReadyCallback called when the operation completes
user_data	data passed to `callback`

Since: 3.0

tracker_sparql_connection_new_finish ()

TrackerSparqlConnection *
tracker_sparql_connection_new_finish (GAsyncResult *result,
                                      GError **error);

Completion function for tracker_sparql_connection_new_async().

Parameters

result	the GAsyncResult
error	pointer to a GError

Since: 3.0

tracker_sparql_connection_remote_new ()

TrackerSparqlConnection *
tracker_sparql_connection_remote_new (const gchar *uri_base);

Connects to a remote SPARQL endpoint. The connection is made using the libsoup HTTP library. The connection will normally use the http:// or https:// protocol.

Parameters

uri_base

Base URI of the remote connection

Returns

a new remote TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

[transfer full]

tracker_sparql_connection_bus_new ()

TrackerSparqlConnection *
tracker_sparql_connection_bus_new (const gchar *service_name,
                                   const gchar *object_path,
                                   GDBusConnection *dbus_connection,
                                   GError **error);

Connects to a database owned by another process on the local machine.

Parameters

service_name	The name of the D-Bus service to connect to.
object_path	The path to the object, or `NULL` to use the default.	[nullable]
dbus_connection	The GDBusConnection to use, or `NULL` to use the session bus.	[nullable]
error	pointer to a GError

Returns

a new TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

[transfer full]

Since: 3.0

tracker_sparql_connection_query ()

TrackerSparqlCursor *
tracker_sparql_connection_query (TrackerSparqlConnection *connection,
                                 const gchar *sparql,
                                 GCancellable *cancellable,
                                 GError **error);

Executes a SPARQL query on. The API call is completely synchronous, so it may block.

The sparql query should be built with TrackerResource, or its parts correctly escaped using tracker_sparql_escape_string(), otherwise SPARQL injection is possible.

Parameters

connection	a TrackerSparqlConnection
sparql	string containing the SPARQL query
cancellable	a GCancellable used to cancel the operation
error	GError for error reporting.

Returns

a TrackerSparqlCursor if results were found. On error, NULL is returned and the error is set accordingly. Call g_object_unref() on the returned cursor when no longer needed.

[transfer full]

tracker_sparql_connection_query_async ()

void
tracker_sparql_connection_query_async (TrackerSparqlConnection *connection,
                                       const gchar *sparql,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Executes asynchronously a SPARQL query.

Parameters

connection	a TrackerSparqlConnection
sparql	string containing the SPARQL query
cancellable	a GCancellable used to cancel the operation
callback	user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
user_data	user-defined data to be passed to `callback`

tracker_sparql_connection_query_finish ()

TrackerSparqlCursor *
tracker_sparql_connection_query_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous SPARQL query operation.

Parameters

connection	a TrackerSparqlConnection
res	a GAsyncResult with the result of the operation
error	GError for error reporting.

Returns

a TrackerSparqlCursor if results were found. On error, NULL is returned and the error is set accordingly. Call g_object_unref() on the returned cursor when no longer needed.

[transfer full]

tracker_sparql_connection_query_statement ()

TrackerSparqlStatement *
tracker_sparql_connection_query_statement
                               (TrackerSparqlConnection *connection,
                                const gchar *sparql,
                                GCancellable *cancellable,
                                GError **error);

Prepares the given sparql as a TrackerSparqlStatement.

Parameters

connection	a TrackerSparqlConnection
sparql	the SPARQL query
cancellable	a GCancellable used to cancel the operation, or `NULL`
error	a TrackerSparqlError or `NULL` if no error occured

Returns

a prepared statement.

[transfer full][nullable]

tracker_sparql_connection_update ()

void
tracker_sparql_connection_update (TrackerSparqlConnection *connection,
                                  const gchar *sparql,
                                  GCancellable *cancellable,
                                  GError **error);

Executes a SPARQL update. The API call is completely synchronous, so it may block.

The sparql query should be built with TrackerResource, or its parts correctly escaped using tracker_sparql_escape_string(), otherwise SPARQL injection is possible.

Parameters

connection	a TrackerSparqlConnection
sparql	string containing the SPARQL update query
cancellable	a GCancellable used to cancel the operation
error	GError for error reporting.

tracker_sparql_connection_update_async ()

void
tracker_sparql_connection_update_async
                               (TrackerSparqlConnection *connection,
                                const gchar *sparql,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Executes asynchronously a SPARQL update.

Parameters

connection	a TrackerSparqlConnection
sparql	string containing the SPARQL update query
cancellable	a GCancellable used to cancel the operation
callback	user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
user_data	user-defined data to be passed to `callback`

tracker_sparql_connection_update_finish ()

void
tracker_sparql_connection_update_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous SPARQL update operation.

Parameters

connection	a TrackerSparqlConnection
res	a GAsyncResult with the result of the operation
error	GError for error reporting.

tracker_sparql_connection_update_array_async ()

void
tracker_sparql_connection_update_array_async
                               (TrackerSparqlConnection *connection,
                                gchar **sparql,
                                gint sparql_length,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Executes asynchronously an array of SPARQL updates. Each update in the array is its own transaction. This means that update n+1 is not halted due to an error in update n.

Parameters

connection	a TrackerSparqlConnection
sparql	an array of strings containing the SPARQL update queries
sparql_length	the amount of strings you pass as `sparql`
cancellable	a GCancellable used to cancel the operation
callback	user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
user_data	user-defined data to be passed to `callback`

tracker_sparql_connection_update_array_finish ()

gboolean
tracker_sparql_connection_update_array_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous SPARQL update_array operation.

Example 1.

static void
async_update_array_callback (GObject      *source_object,
                             GAsyncResult *result,
                             gpointer      user_data)
{
    GError *error = NULL;
    GPtrArray *errors;
    guint i;

    errors = tracker_sparql_connection_update_array_finish (connection, result, &error);
    g_assert_no_error (error);

    for (i = 0; i < errors->len; i++) {
        const GError *e = g_ptr_array_index (errors, i);

        ...
    }

    g_ptr_array_unref (errors);
}

Parameters

connection	a TrackerSparqlConnection
res	a GAsyncResult with the result of the operation
error	GError for error reporting.

Returns

a GPtrArray of size sparql_length with elements that are either NULL or a GError instance. The returned array should be freed with g_ptr_array_unref when no longer used, not with g_ptr_array_free. When you use errors of the array, you must g_error_copy them. Errors inside of the array must be considered as const data and not freed. The index of the error corresponds to the index of the update query in the array that you passed to tracker_sparql_connection_update_array_async.

tracker_sparql_connection_update_blank ()

GVariant *
tracker_sparql_connection_update_blank
                               (TrackerSparqlConnection *connection,
                                const gchar *sparql,
                                GCancellable *cancellable,
                                GError **error);

Executes a SPARQL update and returns the URNs of the generated nodes, if any. The API call is completely synchronous, so it may block.

The sparql query should be built with TrackerResource, or its parts correctly escaped using tracker_sparql_escape_string(), otherwise SPARQL injection is possible.

Parameters

connection	a TrackerSparqlConnection
sparql	string containing the SPARQL update query
cancellable	a GCancellable used to cancel the operation
error	GError for error reporting.

Returns

a GVariant with the generated URNs, which should be freed with g_variant_unref() when no longer used.

tracker_sparql_connection_update_blank_async ()

void
tracker_sparql_connection_update_blank_async
                               (TrackerSparqlConnection *connection,
                                const gchar *sparql,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Executes asynchronously a SPARQL update.

Parameters

connection	a TrackerSparqlConnection
sparql	string containing the SPARQL update query
cancellable	a GCancellable used to cancel the operation
callback	user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
user_data	user-defined data to be passed to `callback`

tracker_sparql_connection_update_blank_finish ()

GVariant *
tracker_sparql_connection_update_blank_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous SPARQL update operation, and returns the URNs of the generated nodes, if any.

Parameters

connection	a TrackerSparqlConnection
res	a GAsyncResult with the result of the operation
error	GError for error reporting.

Returns

a GVariant with the generated URNs, which should be freed with g_variant_unref() when no longer used.

tracker_sparql_connection_update_resource ()

gboolean
tracker_sparql_connection_update_resource
                               (TrackerSparqlConnection *connection,
                                const gchar *graph,
                                TrackerResource *resource,
                                GCancellable *cancellable,
                                GError **error);

Inserts a resource as described by resource , on the graph described by graph . This operation blocks until done.

Parameters

connection	a TrackerSparqlConnection
graph	RDF graph where the resource should be inserted/updated, or `NULL` for the default graph.	[nullable]
resource	a TrackerResource
cancellable	a GCancellable, or `NULL`.	[nullable]
error	pointer to a GError, or `NULL`

Returns

TRUE if there were no errors.

Since: 3.1

tracker_sparql_connection_update_resource_async ()

void
tracker_sparql_connection_update_resource_async
                               (TrackerSparqlConnection *connection,
                                const gchar *graph,
                                TrackerResource *resource,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Inserts a resource as described by resource , on the graph described by graph . This operation is executed asynchronously, when finished callback will be executed.

Parameters

connection	a TrackerSparqlConnection
graph	RDF graph where the resource should be inserted/updated, or `NULL` for the default graph.	[nullable]
resource	a TrackerResource
cancellable	a GCancellable, or `NULL`.	[nullable]
callback	the GAsyncReadyCallback called when the operation completes
user_data	data passed to `callback`

Since: 3.1

tracker_sparql_connection_update_resource_finish ()

gboolean
tracker_sparql_connection_update_resource_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes a tracker_sparql_connection_update_resource_async() operation.

Parameters

connection	a TrackerSparqlConnection
res	a GAsyncResult with the result of the operation
error	pointer to a GError, or `NULL`

Returns

TRUE if there were no errors.

Since: 3.1

tracker_sparql_connection_get_namespace_manager ()

TrackerNamespaceManager *
tracker_sparql_connection_get_namespace_manager
                               (TrackerSparqlConnection *connection);

Retrieves a TrackerNamespaceManager that contains all prefixes in the ontology of connection .

Parameters

connection

a TrackerSparqlConnection

Returns

a TrackerNamespaceManager for this connection. This object is owned by connection and must not be freed.

[transfer none]

tracker_sparql_connection_create_notifier ()

TrackerNotifier *
tracker_sparql_connection_create_notifier
                               (TrackerSparqlConnection *connection);

Creates a new TrackerNotifier to notify about changes in connection . See TrackerNotifier documentation for information about how to use this object.

Parameters

connection

a TrackerSparqlConnection

Returns

a newly created notifier. Free with g_object_unref() when no longer needed.

[transfer full]

tracker_sparql_connection_create_batch ()

TrackerBatch *
tracker_sparql_connection_create_batch
                               (TrackerSparqlConnection *connection);

Creates a new batch to store and execute update commands. If the connection is readonly or cannot issue SPARQL updates, NULL will be returned.

Parameters

connection

a TrackerSparqlConnection

Returns

(nullable): A new TrackerBatch.

[transfer full]

tracker_sparql_connection_close ()

void
tracker_sparql_connection_close (TrackerSparqlConnection *connection);

Closes a SPARQL connection. No other API calls than g_object_unref() should happen after this call.

This call is blocking. All pending updates will be flushed, and the store databases will be closed orderly. All ongoing SELECT queries will be cancelled. Notifiers will no longer emit events.

Parameters

connection

a TrackerSparqlConnection

Since: 3.0

tracker_sparql_connection_close_async ()

void
tracker_sparql_connection_close_async (TrackerSparqlConnection *connection,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Closes a connection asynchronously. No other API calls than g_object_unref() should happen after this call. See tracker_sparql_connection_close() for more information.

Parameters

connection	a TrackerSparqlConnection
cancellable	a GCancellable, or `NULL`
callback	user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
user_data	user-defined data to be passed to `callback`

Since: 3.0

tracker_sparql_connection_close_finish ()

gboolean
tracker_sparql_connection_close_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous connection close.

Parameters

connection	a TrackerSparqlConnection
res	the GAsyncResult
error	pointer to a GError

Returns

FALSE if some error occurred, TRUE otherwise

Since: 3.0

Types and Values

TrackerSparqlConnection

typedef struct _TrackerSparqlConnection TrackerSparqlConnection;

The TrackerSparqlConnection object represents a SPARQL connection.

enum TrackerSparqlConnectionFlags

Connection flags to modify TrackerSparqlConnection behavior.

Members

TRACKER_SPARQL_CONNECTION_FLAGS_NONE	No flags.
TRACKER_SPARQL_CONNECTION_FLAGS_READONLY	Connection is readonly.
TRACKER_SPARQL_CONNECTION_FLAGS_FTS_ENABLE_STEMMER	Word stemming is applied to FTS search terms.
TRACKER_SPARQL_CONNECTION_FLAGS_FTS_ENABLE_UNACCENT	Unaccenting is applied to FTS search terms.
TRACKER_SPARQL_CONNECTION_FLAGS_FTS_ENABLE_STOP_WORDS	FTS Search terms are filtered through a stop word list.
TRACKER_SPARQL_CONNECTION_FLAGS_FTS_IGNORE_NUMBERS	Ignore numbers in FTS search terms.