Connection

Connection

Object Hierarchy:

Description:

[ CCode ( type_id = "tracker_sparql_connection_get_type ()" ) ]
[ GIR ( name = "SparqlConnection" ) ]
public abstract class Connection : Object

`TrackerSparqlConnection` holds a connection to a RDF triple store.

This triple store may be of three types:

Local to the process, created through [ctor@SparqlConnection.new].
A HTTP SPARQL endpoint over the network, created through [ctor@SparqlConnection.remote_new]
A DBus SPARQL endpoint owned by another process in the same machine, created through [ctor@SparqlConnection.bus_new]

When creating a local triple store, it is required to give details about its structure. This is done by passing a location to an ontology, see more on how are [ontologies defined](ontologies.html). A local database may be stored in a filesystem location, or it may reside in memory.

A `TrackerSparqlConnection` is private to the calling process, it can be exposed to other hosts/processes via a [class@Endpoint], see [ ctor@EndpointDBus.new] and [ctor@EndpointHttp.new].

When issuing SPARQL queries and updates, it is recommended that these are created through [class@SparqlStatement] to avoid the SPARQL injection class of bugs, see [method@SparqlConnection.query_statement] and [method@SparqlConnection.update_statement]. For SPARQL updates it is also possible to use a "builder" approach to generate RDF data, see [class@Resource]. It is also possible to create [ class@SparqlStatement] objects for SPARQL queries and updates from SPARQL strings embedded in a [struct@Gio.Resource], see [ method@SparqlConnection.load_statement_from_gresource].

To get the best performance, it is recommended that SPARQL updates are clustered through [class@Batch].

`TrackerSparqlConnection` also offers a number of methods for the simple cases, [method@SparqlConnection.query] may be used when there is a SPARQL query string directly available, and the [method@SparqlConnection.update] family of functions may be used for one-off updates. All functions have asynchronous variants.

When a SPARQL query is executed, a [class@SparqlCursor] will be obtained to iterate over the query results.

Depending on the ontology definition, `TrackerSparqlConnection` may emit notifications whenever resources of certain types get insert, modified or deleted from the triple store (see [nrl:notify](nrl-ontology.html#nrl:notify). These notifications can be handled via a [ class@Notifier] obtained with [method@SparqlConnection.create_notifier].

After done with a connection, it is recommended to call [method@SparqlConnection.close] or [method@SparqlConnection.close_async] explicitly to cleanly close the connection and prevent consistency checks on future runs. The triple store connection will be implicitly closed when the `TrackerSparqlConnection` object is disposed.

A `TrackerSparqlConnection` may be used from multiple threads, asynchronous updates are executed sequentially on arrival order, asynchronous queries are dispatched in a thread pool.

If you ever have the need to procedurally compose SPARQL query strings, consider the use of [func@sparql_escape_string] for literal strings and the [func@sparql_escape_uri] family of functions for URIs.

Namespace: Tracker.Sparql

Package: tracker-sparql-3.0

Content:

Static methods:

public static Connection @new (ConnectionFlags flags, File? store, File? ontology, Cancellable? cancellable = null) throws Error
Creates or opens a process-local database.
public static Connection bus_new (string service_name, string? object_path, DBusConnection? dbus_connection = null) throws Error
service_name (nullable): The name of the D-Bus service to connect to, or null if not using a message bus.
public static async Connection bus_new_async (string service_name, string? object_path, DBusConnection? dbus_connection = null, Cancellable? cancellable = null) throws Error
Connects asynchronously to a database owned by another process on the local machine via DBus.
public static async Connection new_async (ConnectionFlags flags, File? store, File? ontology, Cancellable? cancellable = null) throws Error
Creates or opens a process-local database asynchronously.
public static Connection new_from_rdf (ConnectionFlags flags, File? store, DeserializeFlags deserialize_flags, RdfFormat rdf_format, InputStream rdf_stream, Cancellable? cancellable = null) throws Error
Constructor similar to [ctor@SparqlConnection.
public static async Connection new_from_rdf_async (ConnectionFlags flags, File? store, DeserializeFlags deserialize_flags, RdfFormat rdf_format, InputStream rdf_stream, Cancellable? cancellable = null) throws Error
Asynchronous version of [ctor@SparqlConnection.
public static Connection remote_new (string uri_base)
Creates a connection to a remote HTTP SPARQL endpoint.

Creation methods:

protected Connection ()

Methods:

public void close ()
Closes a SPARQL connection.
public async bool close_async (Cancellable? cancellable = null) throws Error
Closes a SPARQL connection asynchronously.
public Batch create_batch ()
Creates a new [class@Batch] to store and execute SPARQL updates.
public Notifier? create_notifier ()
Creates a new [class@Notifier] to receive notifications about changes in this.
public async bool deserialize_async (DeserializeFlags flags, RdfFormat format, string default_graph, InputStream stream, Cancellable? cancellable = null) throws Error
Loads the RDF data contained in stream into the given this.
public unowned NamespaceManager get_namespace_manager ()
Returns a [class@NamespaceManager] that contains all prefixes in the ontology of this.
public Statement load_statement_from_gresource (string resource_path, Cancellable? cancellable = null) throws Error
Prepares a [class@SparqlStatement] for the SPARQL contained as a [ struct@Gio.
public void map_connection (string handle_name, Connection service_connection)
Maps a `TrackerSparqlConnection` onto another through a `private: handle_name` URI.
public Cursor query (string sparql, Cancellable? cancellable = null) throws Error
Executes a SPARQL query on this.
public async Cursor query_async (string sparql, Cancellable? cancellable = null) throws Error
Executes asynchronously a SPARQL query on this
public Statement query_statement (string sparql, Cancellable? cancellable = null) throws Error
Prepares the given `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL query as a [class@SparqlStatement].
public async InputStream serialize_async (SerializeFlags flags, RdfFormat format, string query, Cancellable? cancellable = null) throws Error
Serializes a `DESCRIBE` or `CONSTRUCT` query into the specified RDF format.
public void update (string sparql, Cancellable? cancellable = null) throws Error
Executes a SPARQL update on this.
public async bool update_array_async (string sparql, int sparql_length, Cancellable? cancellable = null) throws Error
Executes asynchronously an array of SPARQL updates.
public async void update_async (string sparql, Cancellable? cancellable = null) throws Error
Executes asynchronously a SPARQL update.
public Variant update_blank (string sparql, Cancellable? cancellable = null) throws Error
Executes a SPARQL update and returns the names of the generated blank nodes.
public async Variant update_blank_async (string sparql, Cancellable? cancellable = null) throws Error
Executes asynchronously a SPARQL update and returns the names of the generated blank nodes.
public bool update_resource (string? graph, Resource resource, Cancellable? cancellable = null) throws Error
Inserts a resource as described by resource on the given graph.
public async bool update_resource_async (string? graph, Resource resource, Cancellable? cancellable = null) throws Error
Inserts asynchronously a resource as described by resource on the given graph.
public Statement update_statement (string sparql, Cancellable? cancellable = null) throws Error
Prepares the given `INSERT`/`DELETE` SPARQL as a [ class@SparqlStatement].

Inherited Members:

All known members inherited from class GLib.Object