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 ()
void | tracker_sparql_connection_bus_new_async ()
TrackerSparqlConnection * | tracker_sparql_connection_bus_new_finish ()
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_bus_new_async ()

    void
    tracker_sparql_connection_bus_new_async
                                   (const gchar *service_name,
                                    const gchar *object_path,
                                    GDBusConnection *dbus_connection,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Connects to a database owned by another process on the local machine. This is an asynchronous operation.

#### 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]
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_bus_new_finish ()

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

Completion function for `tracker_sparql_connection_bus_new_async()`.

#### Parameters

result | the GAsyncResult |
error | pointer to a GError |

#### Returns

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

[transfer full]

Since: 3.1

### 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. All updates in the array are handled within a single transaction.

#### 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.

#### Parameters

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

#### Returns

TRUE if there were no errors.

### 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. |