Sparql builder

Sparql builder — Creating insertion/update SparQL queries.

Synopsis

                    TrackerSparqlBuilder;
                    TrackerSparqlBuilderClass;
                    TrackerSparqlBuilderPrivate;
enum                TrackerSparqlBuilderState;
TrackerSparqlBuilder* tracker_sparql_builder_new        (void);
TrackerSparqlBuilder* tracker_sparql_builder_new_embedded_insert
                                                        (void);
TrackerSparqlBuilder* tracker_sparql_builder_new_update (void);
TrackerSparqlBuilder* tracker_sparql_builder_construct  (GType object_type);
TrackerSparqlBuilder* tracker_sparql_builder_construct_embedded_insert
                                                        (GType object_type);
TrackerSparqlBuilder* tracker_sparql_builder_construct_update
                                                        (GType object_type);
TrackerSparqlBuilderState  tracker_sparql_builder_get_state
                                                        (TrackerSparqlBuilder *self);
const char*         tracker_sparql_builder_get_result   (TrackerSparqlBuilder *self);
gint                tracker_sparql_builder_get_length   (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_append       (TrackerSparqlBuilder *self,
                                                         const char *raw);
void                tracker_sparql_builder_prepend      (TrackerSparqlBuilder *self,
                                                         const char *raw);
void                tracker_sparql_builder_insert_open  (TrackerSparqlBuilder *self,
                                                         const char *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 char *graph);
void                tracker_sparql_builder_delete_close (TrackerSparqlBuilder *self);
void                tracker_sparql_builder_drop_graph   (TrackerSparqlBuilder *self,
                                                         const char *iri);
void                tracker_sparql_builder_subject_variable
                                                        (TrackerSparqlBuilder *self,
                                                         const char *var_name);
void                tracker_sparql_builder_subject_iri  (TrackerSparqlBuilder *self,
                                                         const char *iri);
void                tracker_sparql_builder_subject      (TrackerSparqlBuilder *self,
                                                         const char *s);
void                tracker_sparql_builder_predicate_iri
                                                        (TrackerSparqlBuilder *self,
                                                         const char *iri);
void                tracker_sparql_builder_predicate    (TrackerSparqlBuilder *self,
                                                         const char *s);
void                tracker_sparql_builder_object_iri   (TrackerSparqlBuilder *self,
                                                         const char *iri);
void                tracker_sparql_builder_object       (TrackerSparqlBuilder *self,
                                                         const char *s);
void                tracker_sparql_builder_object_string
                                                        (TrackerSparqlBuilder *self,
                                                         const char *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,
                                                         double literal);
void                tracker_sparql_builder_object_variable
                                                        (TrackerSparqlBuilder *self,
                                                         const char *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 char *value);

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.

Example 2. Using TrackerSparqlBuilder

  TrackerSparqlBuilder *builder;
  const gchar *iri = "urn:example:0001";
  gchar *query_str;
  
  /* Create builder */
  builder = tracker_sparql_builder_new_update ();
  
  /* Drop previous data */
  tracker_sparql_builder_drop_graph (builder, iri);
  
  /* Insert new data */
  tracker_sparql_builder_insert_open (builder, iri);
  
  tracker_sparql_builder_subject_iri (builder, iri);
  
  tracker_sparql_builder_predicate (builder, "a");
  tracker_sparql_builder_object (builder, "nie:DataObject");
  tracker_sparql_builder_object (builder, "nfo:FileDataObject");
  
  tracker_sparql_builder_predicate (builder, "nfo:fileLastModified");
  tracker_sparql_builder_object_date (builder, time (NULL));
  
  tracker_sparql_builder_insert_close (builder);
  
  /* Get query as string */
  query_str = tracker_sparql_builder_get_result (builder);
  

Details

TrackerSparqlBuilder

typedef struct {
	GObject parent_instance;
	TrackerSparqlBuilderPrivate * priv;
} TrackerSparqlBuilder;

The TrackerSparqlBuilder object represents an insertion/update SparQL query.


TrackerSparqlBuilderClass

typedef struct {
	GObjectClass parent_class;
} TrackerSparqlBuilderClass;


TrackerSparqlBuilderPrivate

typedef struct _TrackerSparqlBuilderPrivate TrackerSparqlBuilderPrivate;


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
} TrackerSparqlBuilderState;


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

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

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

tracker_sparql_builder_construct ()

TrackerSparqlBuilder* tracker_sparql_builder_construct  (GType object_type);

object_type :

Returns :


tracker_sparql_builder_construct_embedded_insert ()

TrackerSparqlBuilder* tracker_sparql_builder_construct_embedded_insert
                                                        (GType object_type);

object_type :

Returns :


tracker_sparql_builder_construct_update ()

TrackerSparqlBuilder* tracker_sparql_builder_construct_update
                                                        (GType object_type);

object_type :

Returns :


tracker_sparql_builder_get_state ()

TrackerSparqlBuilderState  tracker_sparql_builder_get_state
                                                        (TrackerSparqlBuilder *self);

self :

Returns :


tracker_sparql_builder_get_result ()

const char*         tracker_sparql_builder_get_result   (TrackerSparqlBuilder *self);

Returns the constructed SparQL query as a string.

self :

a TrackerSparqlBuilder

Returns :

The created SparQL query.

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.

tracker_sparql_builder_append ()

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

Appends raw, unvalidated content to self.

self :

a TrackerSparqlBuilder

raw :

raw content to append.

tracker_sparql_builder_prepend ()

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

Prepends raw, unvalidated content to self.

self :

a TrackerSparqlBuilder

raw :

raw content to prepend.

tracker_sparql_builder_insert_open ()

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

Opens an insertion statement.

self :

a TrackerSparqlBuilder

graph :

Graph name, or NULL.

tracker_sparql_builder_insert_close ()

void                tracker_sparql_builder_insert_close (TrackerSparqlBuilder *self);

Closes an insertion statement opened with tracker_sparql_builder_insert_open().


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.


tracker_sparql_builder_where_close ()

void                tracker_sparql_builder_where_close  (TrackerSparqlBuilder *self);

Closes a WHERE clause opened through tracker_sparql_builder_where_open().


tracker_sparql_builder_delete_open ()

void                tracker_sparql_builder_delete_open  (TrackerSparqlBuilder *self,
                                                         const char *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.

tracker_sparql_builder_delete_close ()

void                tracker_sparql_builder_delete_close (TrackerSparqlBuilder *self);

Closes a DELETE clause opened through tracker_sparql_builder_delete_close().


tracker_sparql_builder_drop_graph ()

void                tracker_sparql_builder_drop_graph   (TrackerSparqlBuilder *self,
                                                         const char *iri);

Appends a DROP GRAPH clause.

self :

a TrackerSparqlBuilder

iri :

a graph name.

tracker_sparql_builder_subject_variable ()

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

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

self :

a TrackerSparqlBuilder

var_name :

Variable name, without leading '?'

tracker_sparql_builder_subject_iri ()

void                tracker_sparql_builder_subject_iri  (TrackerSparqlBuilder *self,
                                                         const char *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.

tracker_sparql_builder_subject ()

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

Appends a subject.

self :

a TrackerSparqlBuilder

s :

subject string

tracker_sparql_builder_predicate_iri ()

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

Appends a predicate as an IRI.

self :

a TrackerSparqlBuilder

iri :

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

tracker_sparql_builder_predicate ()

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

Appends a predicate for the previously appended subject.

self :

a TrackerSparqlBuilder

s :

predicate string

tracker_sparql_builder_object_iri ()

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

Appends an object as an IRI.

self :

a TrackerSparqlBuilder

iri :

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

tracker_sparql_builder_object ()

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

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

self :

a TrackerSparqlBuilder

s :

object string

tracker_sparql_builder_object_string ()

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

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

self :

a TrackerSparqlBuilder

literal :

string object

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 :

boolean object

tracker_sparql_builder_object_int64 ()

void                tracker_sparql_builder_object_int64 (TrackerSparqlBuilder *self,
                                                         gint64 literal);

Appends a gint64 as an object.

self :

a TrackerSparqlBuilder

literal :

object as gint64

tracker_sparql_builder_object_date ()

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

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

self :

a TrackerSparqlBuilder

literal :

object as time_t

tracker_sparql_builder_object_double ()

void                tracker_sparql_builder_object_double
                                                        (TrackerSparqlBuilder *self,
                                                         double literal);

Appends a gdouble as an object.

self :

a TrackerSparqlBuilder

literal :

object as gdouble

tracker_sparql_builder_object_variable ()

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

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

self :

a TrackerSparqlBuilder

var_name :

variable name, without leading '?'

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.


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()


tracker_sparql_builder_object_unvalidated ()

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

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

self :

a TrackerSparqlBuilder

value :

possibly UTF-8 invalid string.