TrackerSparqlConnection: Tracker SPARQL Library Reference Manual

## TrackerSparqlConnection TrackerSparqlConnection |

## Functions

TrackerSparqlConnection * | tracker_sparql_connection_get ()
void | tracker_sparql_connection_get_async ()
TrackerSparqlConnection * | tracker_sparql_connection_get_finish ()
TrackerSparqlConnection * | tracker_sparql_connection_local_new ()
void | tracker_sparql_connection_local_new_async ()
TrackerSparqlConnection * | tracker_sparql_connection_local_new_finish ()
TrackerSparqlConnection * | tracker_sparql_connection_remote_new ()
TrackerSparqlCursor * | tracker_sparql_connection_query ()
void | tracker_sparql_connection_query_async ()
TrackerSparqlCursor * | tracker_sparql_connection_query_finish ()
void | tracker_sparql_connection_update ()
void | tracker_sparql_connection_update_async ()
void | tracker_sparql_connection_update_finish ()
void | tracker_sparql_connection_update_array_async ()
GPtrArray * | 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 ()
void | tracker_sparql_connection_load ()
void | tracker_sparql_connection_load_async ()
void | tracker_sparql_connection_load_finish ()
TrackerSparqlCursor * | tracker_sparql_connection_statistics ()
void | tracker_sparql_connection_statistics_async ()
TrackerSparqlCursor * | tracker_sparql_connection_statistics_finish ()
TrackerNamespaceManager * | tracker_sparql_connection_get_namespace_manager ()
void | tracker_sparql_connection_set_domain ()
gchar * | tracker_sparql_connection_get_domain ()

## Types and Values

enum | TrackerSparqlError
struct | TrackerSparqlConnection
enum | TrackerSparqlConnectionFlags

## Object Hierarchy

        GObject
        ╰── TrackerSparqlConnection

## Description

## Functions

### tracker_sparql_connection_get ()

    TrackerSparqlConnection *
    tracker_sparql_connection_get (GCancellable *cancellable,
                                   GError **error);

This function is used to give the caller a connection to Tracker they can use for future requests. The best backend available to connect to Tracker is returned. These backends include direct-access (for read-only queries) and D-Bus (for both read and write queries).

You can use environment variables to influence how backends are used. If no environment variables are provided, both backends are loaded and chosen based on their merits. If you try to force a backend for a query which it won't support (i.e. an update for a read-only backend), you will see critical warnings.

When calling either `tracker_sparql_connection_get()`, `tracker_sparql_connection_get_direct()` or the asynchronous variants of these functions, a mutex is used to protect the loading of backends against potential race conditions. For synchronous calls, this function will always block if a previous connection get method has been called.

All backends will call the D-Bus tracker-store API `Wait()` to make sure the store and databases are in the right state before any user based requests can proceed. There may be a small delay during this call if the databases weren't shutdown cleanly and need to be checked on start up. If the journal needs to be replayed in such an event, the delay may be substantial while data is restored as best as possible.

#### Parameters

cancellable | a GCancellable used to cancel the operation |
error | GError for error reporting. |

#### Returns

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

Since: 0.10

### tracker_sparql_connection_get_async ()

    void
    tracker_sparql_connection_get_async (GCancellable *cancellable,
                                         GAsyncReadyCallback _callback_,
                                         gpointer _user_data_);

### tracker_sparql_connection_get_finish ()

    TrackerSparqlConnection *
    tracker_sparql_connection_get_finish (GAsyncResult *_res_,
                                          GError **error);

This function is called from the callback provided for `tracker_sparql_connection_get_async()` to return the connection requested or an error in cases of failure.

#### Parameters

_res_ | The GAsyncResult from the callback used to return the TrackerSparqlConnection |
error | The error which occurred or `NULL` |

#### Returns

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

Since: 0.10

### tracker_sparql_connection_local_new ()

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

#### Parameters

flags | Flags to define connection behavior |
store | Location for the database |
journal | Location for the operation journal, or `NULL` |
ontology | Location of the ontology used for this connection, or `NULL` |
cancellable | A GCancellable |
error | The error which occurred or `NULL` |

#### Returns

a new local TrackerSparqlConnection using the specified `cache` /`journal` locations, and the ontology specified in the `ontology` directory. Call `g_object_unref()` on the object when no longer used.

This database connection is considered entirely private to the calling process, if multiple processes use the same journal/cache locations, the results are unpredictable.

The `journal` is used to rebuild the database in case of data corruption, if `NULL` is provided, the same location than `store` will be assumed.

The caller is entirely free to define an ontology or reuse Nepomuk for its purposes. For the former see the "Defining ontologies" section in this library docs. For the latter pass a `NULL` `ontology` .

The `ontology` argument may be a resource:/// URI, a directory location must be provided, all children .ontology and .description files will be read.

The `store` and `journal` arguments expect directories, and those are assumed to be entirely private to Tracker.

Since: 2.0

### tracker_sparql_connection_local_new_async ()

    void
    tracker_sparql_connection_local_new_async
                                   (TrackerSparqlConnectionFlags flags,
                                    GFile *store,
                                    GFile *journal,
                                    GFile *ontology,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

#### Parameters

flags | Flags to define connection behavior |
store | Location for the database |
journal | Location for the operation journal, or `NULL` |
ontology | Location of the ontology used for this connection, or `NULL` |
cancellable | A GCancellable |
_callback_ | user-defined GAsyncReadyCallback to be called when asynchronous operation is finished. |
_user_data_ | user-defined data to be passed to `_callback_` |

#### Returns

a new local TrackerSparqlConnection using the specified `cache` /`journal` locations, and the ontology specified in the `ontology` directory. Call `g_object_unref()` on the object when no longer used.

See `tracker_sparql_connection_local_new()` for more details.

Since: 2.0

### tracker_sparql_connection_local_new_finish ()

    TrackerSparqlConnection *
    tracker_sparql_connection_local_new_finish
                                   (GAsyncResult *_res_,
                                    GError **error);

### tracker_sparql_connection_remote_new ()

    TrackerSparqlConnection *
    tracker_sparql_connection_remote_new (const gchar *uri_base);

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

Since: 1.12

### tracker_sparql_connection_query ()

    TrackerSparqlCursor *
    tracker_sparql_connection_query (TrackerSparqlConnection *self,
                                     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 TrackerSparqlBuilder, or its parts correctly escaped using `tracker_sparql_escape_string()`, otherwise SPARQL injection is possible.

#### Parameters

self | 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, NULL otherwise. On error, NULL is returned and the `error` is set accordingly. Call `g_object_unref()` on the returned cursor when no longer needed.

Since: 0.10

### tracker_sparql_connection_query_async ()

    void
    tracker_sparql_connection_query_async (TrackerSparqlConnection *self,
                                           const gchar *sparql,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback _callback_,
                                           gpointer _user_data_);

### tracker_sparql_connection_query_finish ()

    TrackerSparqlCursor *
    tracker_sparql_connection_query_finish
                                   (TrackerSparqlConnection *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Finishes the asynchronous SPARQL query operation.

#### Parameters

self | a TrackerSparqlConnection |
_res_ | a GAsyncResult with the result of the operation |
error | GError for error reporting. |

#### Returns

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

Since: 0.10

### tracker_sparql_connection_update ()

    void
    tracker_sparql_connection_update (TrackerSparqlConnection *self,
                                      const gchar *sparql,
                                      gint priority,
                                      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 TrackerSparqlBuilder, or its parts correctly escaped using `tracker_sparql_escape_string()`, otherwise SPARQL injection is possible.

#### Parameters

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

Since: 0.10

### tracker_sparql_connection_update_async ()

    void
    tracker_sparql_connection_update_async
                                   (TrackerSparqlConnection *self,
                                    const gchar *sparql,
                                    gint priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Executes asynchronously a SPARQL update.

#### Parameters

self | a TrackerSparqlConnection |
sparql | string containing the SPARQL update query |
priority | the priority for the asynchronous operation |
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_` |

Since: 0.10

### tracker_sparql_connection_update_finish ()

    void
    tracker_sparql_connection_update_finish
                                   (TrackerSparqlConnection *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Finishes the asynchronous SPARQL update operation.

#### Parameters

self | a TrackerSparqlConnection |
_res_ | a GAsyncResult with the result of the operation |
error | GError for error reporting. |

Since: 0.10

### tracker_sparql_connection_update_array_async ()

    void
    tracker_sparql_connection_update_array_async
                                   (TrackerSparqlConnection *self,
                                    gchar **sparql,
                                    int sparql_length1,
                                    gint priority,
                                    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

self | a TrackerSparqlConnection |
sparql | an array of strings containing the SPARQL update queries |
sparql_length1 | the amount of strings you pass as `sparql` |
priority | the priority for the asynchronous operation |
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_` |

Since: 0.10

### tracker_sparql_connection_update_array_finish ()

    GPtrArray *
    tracker_sparql_connection_update_array_finish
                                   (TrackerSparqlConnection *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Finishes the asynchronous SPARQL update_array operation.

Example 1.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    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

self | a TrackerSparqlConnection |
_res_ | a GAsyncResult with the result of the operation |
error | GError for error reporting. |

#### Returns

a GPtrArray of size `sparql_length1` 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.

Since: 0.10

### tracker_sparql_connection_update_blank ()

    GVariant *
    tracker_sparql_connection_update_blank
                                   (TrackerSparqlConnection *self,
                                    const gchar *sparql,
                                    gint priority,
                                    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 TrackerSparqlBuilder, or its parts correctly escaped using `tracker_sparql_escape_string()`, otherwise SPARQL injection is possible.

#### Parameters

self | a TrackerSparqlConnection |
sparql | string containing the SPARQL update query |
priority | the priority for the operation |
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.

Since: 0.10

### tracker_sparql_connection_update_blank_async ()

    void
    tracker_sparql_connection_update_blank_async
                                   (TrackerSparqlConnection *self,
                                    const gchar *sparql,
                                    gint priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Executes asynchronously a SPARQL update.

#### Parameters

self | a TrackerSparqlConnection |
sparql | string containing the SPARQL update query |
priority | the priority for the asynchronous operation |
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_` |

Since: 0.10

### tracker_sparql_connection_update_blank_finish ()

    GVariant *
    tracker_sparql_connection_update_blank_finish
                                   (TrackerSparqlConnection *self,
                                    GAsyncResult *_res_,
                                    GError **error);

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

#### Parameters

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

Since: 0.10

### tracker_sparql_connection_load ()

    void
    tracker_sparql_connection_load (TrackerSparqlConnection *self,
                                    GFile *file,
                                    GCancellable *cancellable,
                                    GError **error);

Loads a Turtle file (TTL) into the store. The API call is completely synchronous, so it may block.

#### Parameters

self | a TrackerSparqlConnection |
file | a GFile |
cancellable | a GCancellable used to cancel the operation |
error | GError for error reporting. |

Since: 0.10

### tracker_sparql_connection_load_async ()

    void
    tracker_sparql_connection_load_async (TrackerSparqlConnection *self,
                                          GFile *file,
                                          GCancellable *cancellable,
                                          GAsyncReadyCallback _callback_,
                                          gpointer _user_data_);

Loads, asynchronously, a Turtle file (TTL) into the store.

#### Parameters

self | a TrackerSparqlConnection |
file | a GFile |
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_` |

Since: 0.10

### tracker_sparql_connection_load_finish ()

    void
    tracker_sparql_connection_load_finish (TrackerSparqlConnection *self,
                                           GAsyncResult *_res_,
                                           GError **error);

Finishes the asynchronous load of the Turtle file.

#### Parameters

self | a TrackerSparqlConnection |
_res_ | a GAsyncResult with the result of the operation |
error | GError for error reporting. |

Since: 0.10

### tracker_sparql_connection_statistics ()

    TrackerSparqlCursor *
    tracker_sparql_connection_statistics (TrackerSparqlConnection *self,
                                          GCancellable *cancellable,
                                          GError **error);

Retrieves the statistics from the Store. The API call is completely synchronous, so it may block.

#### Parameters

self | a TrackerSparqlConnection |
cancellable | a GCancellable used to cancel the operation |
error | GError for error reporting. |

#### Returns

a TrackerSparqlCursor to iterate the reply if successful, NULL on error. Call `g_object_unref()` on the returned cursor when no longer needed.

Since: 0.10

### tracker_sparql_connection_statistics_async ()

    void
    tracker_sparql_connection_statistics_async
                                   (TrackerSparqlConnection *self,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Retrieves, asynchronously, the statistics from the Store.

#### Parameters

self | a TrackerSparqlConnection |
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_` |

Since: 0.10

### tracker_sparql_connection_statistics_finish ()

    TrackerSparqlCursor *
    tracker_sparql_connection_statistics_finish
                                   (TrackerSparqlConnection *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Finishes the asynchronous retrieval of statistics from the Store.

#### Parameters

self | a TrackerSparqlConnection |
_res_ | a GAsyncResult with the result of the operation |
error | GError for error reporting. |

#### Returns

a TrackerSparqlCursor to iterate the reply if successful, NULL on error. Call `g_object_unref()` on the returned cursor when no longer needed.

Since: 0.10

### tracker_sparql_connection_get_namespace_manager ()

    TrackerNamespaceManager *
    tracker_sparql_connection_get_namespace_manager
                                   (TrackerSparqlConnection *self);

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

#### Parameters

self | a TrackerSparqlConnection |

#### Returns

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

[transfer none]

Since: 2.0

### tracker_sparql_connection_set_domain ()

    void
    tracker_sparql_connection_set_domain (const gchar *domain);

Sets the domain (usually a DBus name or application ID) that will be used on on the connection obtained by `tracker_sparql_connection_get()`. See the "Isolating tracker-store clients" section in the docs for this library.

This function must be called before any `tracker_sparql_connection_get()` calls happen.

#### Parameters

domain | The domain name for the default connection |

Since: 2.0

### tracker_sparql_connection_get_domain ()

    gchar *
    tracker_sparql_connection_get_domain (void);

Gets the domain (usually a DBus name or application ID) that will be used on on the connection obtained by `tracker_sparql_connection_get()`. See `tracker_sparql_connection_set_domain()` for more information.

#### Returns

The domain string, or `NULL` if none is set.

[transfer full]

Since: 2.0

## Types and Values

### enum TrackerSparqlError

#### Members

TRACKER_SPARQL_ERROR_PARSE |  |
TRACKER_SPARQL_ERROR_UNKNOWN_CLASS |  |
TRACKER_SPARQL_ERROR_UNKNOWN_PROPERTY |  |
TRACKER_SPARQL_ERROR_TYPE |  |
TRACKER_SPARQL_ERROR_CONSTRAINT |  |
TRACKER_SPARQL_ERROR_NO_SPACE |  |
TRACKER_SPARQL_ERROR_INTERNAL |  |
TRACKER_SPARQL_ERROR_UNSUPPORTED |  |

### struct TrackerSparqlConnection

    struct TrackerSparqlConnection;

The TrackerSparqlConnection object represents a connection with the Tracker store or databases depending on direct or non-direct requests.

### enum TrackerSparqlConnectionFlags

#### Members

TRACKER_SPARQL_CONNECTION_FLAGS_NONE |  |
TRACKER_SPARQL_CONNECTION_FLAGS_READONLY |  |