TrackerSparqlBuilder

TrackerSparqlBuilder — Creating insertion/update SPARQL queries.

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <tracker-sparql.h>

struct              TrackerSparqlBuilder;
enum                TrackerSparqlBuilderState;
TrackerSparqlBuilder * tracker_sparql_builder_new       (void);
TrackerSparqlBuilder * tracker_sparql_builder_new_embedded_insert
                                                        (void);
TrackerSparqlBuilder * tracker_sparql_builder_new_update
                                                        (void);
TrackerSparqlBuilderState tracker_sparql_builder_get_state
                                                        (TrackerSparqlBuilder *self);
const gchar *       tracker_sparql_builder_get_result   (TrackerSparqlBuilder *self);
gint                tracker_sparql_builder_get_length   (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_append       (TrackerSparqlBuilder *self,
                                                         const gchar *raw);
void                tracker_sparql_builder_prepend      (TrackerSparqlBuilder *self,
                                                         const gchar *raw);
void                tracker_sparql_builder_insert_open  (TrackerSparqlBuilder *self,
                                                         const gchar *graph);
void                tracker_sparql_builder_insert_silent_open
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *graph);
void                tracker_sparql_builder_insert_close (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_where_open   (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_where_close  (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_delete_open  (TrackerSparqlBuilder *self,
                                                         const gchar *graph);
void                tracker_sparql_builder_delete_close (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_graph_open   (TrackerSparqlBuilder *self,
                                                         const gchar *graph);
void                tracker_sparql_builder_graph_close  (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_subject_variable
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *var_name);
void                tracker_sparql_builder_subject_iri  (TrackerSparqlBuilder *self,
                                                         const gchar *iri);
void                tracker_sparql_builder_subject      (TrackerSparqlBuilder *self,
                                                         const gchar *s);
void                tracker_sparql_builder_predicate_iri
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *iri);
void                tracker_sparql_builder_predicate    (TrackerSparqlBuilder *self,
                                                         const gchar *s);
void                tracker_sparql_builder_object_iri   (TrackerSparqlBuilder *self,
                                                         const gchar *iri);
void                tracker_sparql_builder_object       (TrackerSparqlBuilder *self,
                                                         const gchar *s);
void                tracker_sparql_builder_object_string
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *literal);
void                tracker_sparql_builder_object_boolean
                                                        (TrackerSparqlBuilder *self,
                                                         gboolean literal);
void                tracker_sparql_builder_object_int64 (TrackerSparqlBuilder *self,
                                                         gint64 literal);
void                tracker_sparql_builder_object_date  (TrackerSparqlBuilder *self,
                                                         time_t *literal);
void                tracker_sparql_builder_object_double
                                                        (TrackerSparqlBuilder *self,
                                                         gdouble literal);
void                tracker_sparql_builder_object_variable
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *var_name);
void                tracker_sparql_builder_object_blank_open
                                                        (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_object_blank_close
                                                        (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_object_unvalidated
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *value);

Object Hierarchy

  GObject
   +----TrackerSparqlBuilder
  GEnum
   +----TrackerSparqlBuilderState

Properties

  "length"                   gint                  : Read
  "result"                   gchar*                : Read
  "state"                    TrackerSparqlBuilderState  : Read

Description

TrackerSparqlBuilder is an object what will gather a set of subject/predicate/object triples, together with an optional WHERE clause, in order to create a query that may be issued to tracker-store.

When using TrackerSparqlBuilder, note that you may append several predicates for the same subject, and several objects for the same predicate.

Details

struct TrackerSparqlBuilder

struct TrackerSparqlBuilder;

The TrackerSparqlBuilder object represents an insertion/update SPARQL query.


enum TrackerSparqlBuilderState

typedef enum {
	TRACKER_SPARQL_BUILDER_STATE_UPDATE,
	TRACKER_SPARQL_BUILDER_STATE_INSERT,
	TRACKER_SPARQL_BUILDER_STATE_DELETE,
	TRACKER_SPARQL_BUILDER_STATE_SUBJECT,
	TRACKER_SPARQL_BUILDER_STATE_PREDICATE,
	TRACKER_SPARQL_BUILDER_STATE_OBJECT,
	TRACKER_SPARQL_BUILDER_STATE_BLANK,
	TRACKER_SPARQL_BUILDER_STATE_WHERE,
	TRACKER_SPARQL_BUILDER_STATE_EMBEDDED_INSERT,
	TRACKER_SPARQL_BUILDER_STATE_GRAPH
} TrackerSparqlBuilderState;

Enumeration with the possible states of the SPARQL Builder

TRACKER_SPARQL_BUILDER_STATE_UPDATE

Builder is generating an UPDATE

TRACKER_SPARQL_BUILDER_STATE_INSERT

Builder is generating an INSERT

TRACKER_SPARQL_BUILDER_STATE_DELETE

Builder is generating a DELETE

TRACKER_SPARQL_BUILDER_STATE_SUBJECT

Builder is generating the subject of the query

TRACKER_SPARQL_BUILDER_STATE_PREDICATE

Builder is generating the predicate of the query

TRACKER_SPARQL_BUILDER_STATE_OBJECT

Builder is generating the object of the query

TRACKER_SPARQL_BUILDER_STATE_BLANK

Builder is generating a blank node subject

TRACKER_SPARQL_BUILDER_STATE_WHERE

Builder is generating the WHERE clause contents

TRACKER_SPARQL_BUILDER_STATE_EMBEDDED_INSERT

Builder is generating an embedded INSERT

TRACKER_SPARQL_BUILDER_STATE_GRAPH

Builder is generating the GRAPH clause contents

tracker_sparql_builder_new ()

TrackerSparqlBuilder * tracker_sparql_builder_new       (void);

Creates a stateless TrackerSparqlBuilder.

Returns :

a newly created TrackerSparqlBuilder. Free with g_object_unref() when done

Since 0.10


tracker_sparql_builder_new_embedded_insert ()

TrackerSparqlBuilder * tracker_sparql_builder_new_embedded_insert
                                                        (void);

Creates a TrackerSparqlBuilder ready to be embedded in another query. In embedded inserts, the subject is implied (responsibility of the embedder), so only calls to append predicates and objects for the given subject are allowed.

Returns :

a newly created TrackerSparqlBuilder. Free with g_object_unref() when done

Since 0.10


tracker_sparql_builder_new_update ()

TrackerSparqlBuilder * tracker_sparql_builder_new_update
                                                        (void);

Creates an empty TrackerSparqlBuilder for an update query.

Returns :

a newly created TrackerSparqlBuilder. Free with g_object_unref() when done

Since 0.10


tracker_sparql_builder_get_state ()

TrackerSparqlBuilderState tracker_sparql_builder_get_state
                                                        (TrackerSparqlBuilder *self);

Returns the current state of self

self :

a TrackerSparqlBuilder

Returns :

a TrackerSparqlBuilderState defining the current state of self

Since 0.10


tracker_sparql_builder_get_result ()

const gchar *       tracker_sparql_builder_get_result   (TrackerSparqlBuilder *self);

Retrieves a string representation of the constructed SPARQL query.

self :

a TrackerSparqlBuilder

Returns :

the created SPARQL query. The string is contained in the TrackerSparqlBuilder object, and should not be freed by the caller.

Since 0.10


tracker_sparql_builder_get_length ()

gint                tracker_sparql_builder_get_length   (TrackerSparqlBuilder *self);

Returns the number of objects added to self.

self :

a TrackerSparqlBuilder

Returns :

the number of objects contained.

Since 0.10


tracker_sparql_builder_append ()

void                tracker_sparql_builder_append       (TrackerSparqlBuilder *self,
                                                         const gchar *raw);

Appends raw, unvalidated content to self.

self :

a TrackerSparqlBuilder

raw :

raw content to append.

Since 0.10


tracker_sparql_builder_prepend ()

void                tracker_sparql_builder_prepend      (TrackerSparqlBuilder *self,
                                                         const gchar *raw);

Prepends raw, unvalidated content to self.

self :

a TrackerSparqlBuilder

raw :

raw content to prepend.

Since 0.10


tracker_sparql_builder_insert_open ()

void                tracker_sparql_builder_insert_open  (TrackerSparqlBuilder *self,
                                                         const gchar *graph);

Opens an insertion statement.

self :

a TrackerSparqlBuilder

graph :

graph name, or NULL.

Since 0.10


tracker_sparql_builder_insert_silent_open ()

void                tracker_sparql_builder_insert_silent_open
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *graph);

Opens a silent insertion statement.

self :

a TrackerSparqlBuilder

graph :

graph name, or NULL.

Since 0.10


tracker_sparql_builder_insert_close ()

void                tracker_sparql_builder_insert_close (TrackerSparqlBuilder *self);

Closes an insertion statement opened with tracker_sparql_builder_insert_open().

Since 0.10


tracker_sparql_builder_where_open ()

void                tracker_sparql_builder_where_open   (TrackerSparqlBuilder *self);

Opens a WHERE clause. Data triples may be appended then to narrow the scope to which the update query applies.

Since 0.10


tracker_sparql_builder_where_close ()

void                tracker_sparql_builder_where_close  (TrackerSparqlBuilder *self);

Closes a WHERE clause opened through tracker_sparql_builder_where_open().

Since 0.10


tracker_sparql_builder_delete_open ()

void                tracker_sparql_builder_delete_open  (TrackerSparqlBuilder *self,
                                                         const gchar *graph);

Opens a DELETE clause. Data triples may be appended in order to prepare a query to delete them.

self :

a TrackerSparqlBuilder

graph :

graph name, or NULL.

Since 0.10


tracker_sparql_builder_delete_close ()

void                tracker_sparql_builder_delete_close (TrackerSparqlBuilder *self);

Closes a DELETE clause opened through tracker_sparql_builder_delete_open().

Since 0.10


tracker_sparql_builder_graph_open ()

void                tracker_sparql_builder_graph_open   (TrackerSparqlBuilder *self,
                                                         const gchar *graph);

Opens a GRAPH clause within INSERT, DELETE, or WHERE.

self :

a TrackerSparqlBuilder

graph :

graph name.

Since 0.10


tracker_sparql_builder_graph_close ()

void                tracker_sparql_builder_graph_close  (TrackerSparqlBuilder *self);

Closes a GRAPH clause opened through tracker_sparql_builder_graph_open().

Since 0.10


tracker_sparql_builder_subject_variable ()

void                tracker_sparql_builder_subject_variable
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *var_name);

Appends a subject as a SPARQL variable, such as "?urn".

self :

a TrackerSparqlBuilder

var_name :

variable name, without leading '?'

Since 0.10


tracker_sparql_builder_subject_iri ()

void                tracker_sparql_builder_subject_iri  (TrackerSparqlBuilder *self,
                                                         const gchar *iri);

Appends a subject as an IRI, such as "<urn:file:1234-5678>". IRIs univocally identify a resource in tracker-store.

self :

a TrackerSparqlBuilder

iri :

IRI name, without leading and trailing greater/less than symbols.

Since 0.10


tracker_sparql_builder_subject ()

void                tracker_sparql_builder_subject      (TrackerSparqlBuilder *self,
                                                         const gchar *s);

Appends a subject.

self :

a TrackerSparqlBuilder

s :

subject string

Since 0.10


tracker_sparql_builder_predicate_iri ()

void                tracker_sparql_builder_predicate_iri
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *iri);

Appends a predicate as an IRI.

self :

a TrackerSparqlBuilder

iri :

IRI name, without leading and trailing greater/less than symbols.

Since 0.10


tracker_sparql_builder_predicate ()

void                tracker_sparql_builder_predicate    (TrackerSparqlBuilder *self,
                                                         const gchar *s);

Appends a predicate for the previously appended subject.

self :

a TrackerSparqlBuilder

s :

predicate string

Since 0.10


tracker_sparql_builder_object_iri ()

void                tracker_sparql_builder_object_iri   (TrackerSparqlBuilder *self,
                                                         const gchar *iri);

Appends an object as an IRI.

self :

a TrackerSparqlBuilder

iri :

IRI name, without leading and trailing greater/less than symbols.

Since 0.10


tracker_sparql_builder_object ()

void                tracker_sparql_builder_object       (TrackerSparqlBuilder *self,
                                                         const gchar *s);

Appends a free-form object for the previously appended subject and predicate.

self :

a TrackerSparqlBuilder

s :

object string

Since 0.10


tracker_sparql_builder_object_string ()

void                tracker_sparql_builder_object_string
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *literal);

Appends an object formatted as an string. literal will be escaped and surrounded by double quotes.

self :

a TrackerSparqlBuilder

literal :

string object

Since 0.10


tracker_sparql_builder_object_boolean ()

void                tracker_sparql_builder_object_boolean
                                                        (TrackerSparqlBuilder *self,
                                                         gboolean literal);

Appends a gboolean value as an object.

self :

a TrackerSparqlBuilder

literal :

object as a gboolean

Since 0.10


tracker_sparql_builder_object_int64 ()

void                tracker_sparql_builder_object_int64 (TrackerSparqlBuilder *self,
                                                         gint64 literal);

Appends a gint64 value as an object.

self :

a TrackerSparqlBuilder

literal :

object as a gint64

Since 0.10


tracker_sparql_builder_object_date ()

void                tracker_sparql_builder_object_date  (TrackerSparqlBuilder *self,
                                                         time_t *literal);

Appends a time_t value as an object. literal will be converted to a string in the date format used by tracker-store.

self :

a TrackerSparqlBuilder

literal :

object as a time_t

Since 0.10


tracker_sparql_builder_object_double ()

void                tracker_sparql_builder_object_double
                                                        (TrackerSparqlBuilder *self,
                                                         gdouble literal);

Appends a gdouble value as an object.

self :

a TrackerSparqlBuilder

literal :

object as a gdouble

Since 0.10


tracker_sparql_builder_object_variable ()

void                tracker_sparql_builder_object_variable
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *var_name);

Appends an object as a SparQL variable, such as "?urn".

self :

a TrackerSparqlBuilder

var_name :

variable name, without leading '?'

Since 0.10


tracker_sparql_builder_object_blank_open ()

void                tracker_sparql_builder_object_blank_open
                                                        (TrackerSparqlBuilder *self);

Opens an anonymous blank node. In insertions this can be used to create anonymous nodes for not previously known data without the need of a separate insertion.

Since 0.10


tracker_sparql_builder_object_blank_close ()

void                tracker_sparql_builder_object_blank_close
                                                        (TrackerSparqlBuilder *self);

Closes an anomymous blank node opened with tracker_sparql_builder_object_blank_open()

Since 0.10


tracker_sparql_builder_object_unvalidated ()

void                tracker_sparql_builder_object_unvalidated
                                                        (TrackerSparqlBuilder *self,
                                                         const gchar *value);

Appends a string not validated as UTF-8 as an object.

self :

a TrackerSparqlBuilder

value :

possibly UTF-8 invalid string.

Since 0.10

Property Details

The "length" property

  "length"                   gint                  : Read

Number of objects added to the TrackerSparqlBuilder.

Default value: 0

Since 0.10


The "result" property

  "result"                   gchar*                : Read

String containing the constructed SPARQL in the TrackerSparqlBuilder.

Default value: NULL

Since 0.10


The "state" property

  "state"                    TrackerSparqlBuilderState  : Read

Current state of the TrackerSparqlBuilder.

Default value: TRACKER_SPARQL_BUILDER_STATE_UPDATE

Since 0.10