## 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 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_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_drop_graph   (TrackerSparqlBuilder *self,
                                                             const gchar *iri);
    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);

## 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);

### Warning

`tracker_sparql_builder_new` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_new()` in libtracker-sparql instead.

Creates a stateless TrackerSparqlBuilder.

Returns : | a newly created TrackerSparqlBuilder. Free with `g_object_unref()` when done

Since 0.8

### tracker_sparql_builder_new_embedded_insert ()

    TrackerSparqlBuilder* tracker_sparql_builder_new_embedded_insert
                                                            (void);

### Warning

`tracker_sparql_builder_new_embedded_insert` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_new_embedded_insert()` in libtracker-sparql instead.

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

### tracker_sparql_builder_new_update ()

    TrackerSparqlBuilder* tracker_sparql_builder_new_update (void);

### Warning

`tracker_sparql_builder_new_update` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_new_update()` in libtracker-sparql instead.

Creates an empty TrackerSparqlBuilder for an update query.

Returns : | a newly created TrackerSparqlBuilder. Free with `g_object_unref()` when done

Since 0.8

### tracker_sparql_builder_construct ()

    TrackerSparqlBuilder* tracker_sparql_builder_construct  (GType object_type);

### Warning

`tracker_sparql_builder_construct` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_construct()` in libtracker-sparql instead.

`object_type` : |
Returns : |

Since 0.8

### tracker_sparql_builder_construct_embedded_insert ()

    TrackerSparqlBuilder* tracker_sparql_builder_construct_embedded_insert
                                                            (GType object_type);

### Warning

`tracker_sparql_builder_construct_embedded_insert` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_construct_embedded_insert()` in libtracker-sparql instead.

`object_type` : |
Returns : |

Since 0.8

### tracker_sparql_builder_construct_update ()

    TrackerSparqlBuilder* tracker_sparql_builder_construct_update
                                                            (GType object_type);

### Warning

`tracker_sparql_builder_construct_update` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_construct_update()` in libtracker-sparql instead.

`object_type` : |
Returns : |

Since 0.8

### tracker_sparql_builder_get_state ()

    TrackerSparqlBuilderState  tracker_sparql_builder_get_state
                                                            (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_get_state` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_get_state()` in libtracker-sparql instead.

`self` : |
Returns : |

Since 0.8

### tracker_sparql_builder_get_result ()

    const gchar*        tracker_sparql_builder_get_result   (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_get_result` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_get_result()` in libtracker-sparql instead.

Returns the constructed SparQL query as a string.

`self` : | a TrackerSparqlBuilder
Returns : | The created SparQL query.

Since 0.8

### tracker_sparql_builder_get_length ()

    gint                tracker_sparql_builder_get_length   (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_get_length` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_get_length()` in libtracker-sparql instead.

Returns the number of objects added to `self`.

`self` : | a TrackerSparqlBuilder
Returns : | The number of objects contained.

Since 0.8

### tracker_sparql_builder_append ()

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

### Warning

`tracker_sparql_builder_append` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_append()` in libtracker-sparql instead.

Appends raw, unvalidated content to `self`.

`self` : | a TrackerSparqlBuilder
`raw` : | raw content to append.

Since 0.8

### tracker_sparql_builder_prepend ()

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

### Warning

`tracker_sparql_builder_prepend` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_prepend()` in libtracker-sparql instead.

Prepends raw, unvalidated content to `self`.

`self` : | a TrackerSparqlBuilder
`raw` : | raw content to prepend.

Since 0.8

### tracker_sparql_builder_insert_open ()

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

### Warning

`tracker_sparql_builder_insert_open` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_insert_open()` in libtracker-sparql instead.

Opens an insertion statement.

`self` : | a TrackerSparqlBuilder
`graph` : | Graph name, or `NULL`.

Since 0.8

### tracker_sparql_builder_insert_close ()

    void                tracker_sparql_builder_insert_close (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_insert_close` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_insert_close()` in libtracker-sparql instead.

Closes an insertion statement opened with `tracker_sparql_builder_insert_open()`.

`self` : | a TrackerSparqlBuilder

Since 0.8

### tracker_sparql_builder_where_open ()

    void                tracker_sparql_builder_where_open   (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_where_open` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_where_open()` in libtracker-sparql instead.

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

`self` : | a TrackerSparqlBuilder

Since 0.8

### tracker_sparql_builder_where_close ()

    void                tracker_sparql_builder_where_close  (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_where_close` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_where_close()` in libtracker-sparql instead.

Closes a WHERE clause opened through `tracker_sparql_builder_where_open()`.

`self` : | a TrackerSparqlBuilder

Since 0.8

### tracker_sparql_builder_delete_open ()

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

### Warning

`tracker_sparql_builder_delete_open` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_delete_open()` in libtracker-sparql instead.

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

### tracker_sparql_builder_delete_close ()

    void                tracker_sparql_builder_delete_close (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_delete_close` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_delete_close()` in libtracker-sparql instead.

Closes a DELETE clause opened through `tracker_sparql_builder_delete_close()`.

`self` : | a TrackerSparqlBuilder

Since 0.8

### tracker_sparql_builder_drop_graph ()

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

### Warning

`tracker_sparql_builder_drop_graph` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_drop_graph()` in libtracker-sparql instead.

Appends a DROP GRAPH clause.

`self` : | a TrackerSparqlBuilder
`iri` : | a graph name.

Since 0.8

### tracker_sparql_builder_subject_variable ()

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

### Warning

`tracker_sparql_builder_subject_variable` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_subject_variable()` in libtracker-sparql instead.

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

`self` : | a TrackerSparqlBuilder
`var_name` : | Variable name, without leading '?'

Since 0.8

### tracker_sparql_builder_subject_iri ()

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

### Warning

`tracker_sparql_builder_subject_iri` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_subject_iri()` in libtracker-sparql instead.

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

### tracker_sparql_builder_subject ()

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

### Warning

`tracker_sparql_builder_subject` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_subject()` in libtracker-sparql instead.

Appends a subject.

`self` : | a TrackerSparqlBuilder
`s` : | subject string

Since 0.8

### tracker_sparql_builder_predicate_iri ()

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

### Warning

`tracker_sparql_builder_predicate_iri` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_predicate_iri()` in libtracker-sparql instead.

Appends a predicate as an IRI.

`self` : | a TrackerSparqlBuilder
`iri` : | IRI name, without leading and trailing greater/less than symbols.

Since 0.8

### tracker_sparql_builder_predicate ()

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

### Warning

`tracker_sparql_builder_predicate` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_predicate()` in libtracker-sparql instead.

Appends a predicate for the previously appended subject.

`self` : | a TrackerSparqlBuilder
`s` : | predicate string

Since 0.8

### tracker_sparql_builder_object_iri ()

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

### Warning

`tracker_sparql_builder_object_iri` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_iri()` in libtracker-sparql instead.

Appends an object as an IRI.

`self` : | a TrackerSparqlBuilder
`iri` : | IRI name, without leading and trailing greater/less than symbols.

Since 0.8

### tracker_sparql_builder_object ()

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

### Warning

`tracker_sparql_builder_object` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object()` in libtracker-sparql instead.

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

`self` : | a TrackerSparqlBuilder
`s` : | object string

Since 0.8

### tracker_sparql_builder_object_string ()

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

### Warning

`tracker_sparql_builder_object_string` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_string()` in libtracker-sparql instead.

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

`self` : | a TrackerSparqlBuilder
`literal` : | string object

Since 0.8

### tracker_sparql_builder_object_boolean ()

    void                tracker_sparql_builder_object_boolean
                                                            (TrackerSparqlBuilder *self,
                                                             gboolean literal);

### Warning

`tracker_sparql_builder_object_boolean` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_boolean()` in libtracker-sparql instead.

Appends a gboolean value as an object.

`self` : | a TrackerSparqlBuilder
`literal` : | boolean object

Since 0.8

### tracker_sparql_builder_object_int64 ()

    void                tracker_sparql_builder_object_int64 (TrackerSparqlBuilder *self,
                                                             gint64 literal);

### Warning

`tracker_sparql_builder_object_int64` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_int64()` in libtracker-sparql instead.

Appends a gint64 as an object.

`self` : | a TrackerSparqlBuilder
`literal` : | object as gint64

Since 0.8

### tracker_sparql_builder_object_date ()

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

### Warning

`tracker_sparql_builder_object_date` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_date()` in libtracker-sparql instead.

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

Since 0.8

### tracker_sparql_builder_object_double ()

    void                tracker_sparql_builder_object_double
                                                            (TrackerSparqlBuilder *self,
                                                             gdouble literal);

### Warning

`tracker_sparql_builder_object_double` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_double()` in libtracker-sparql instead.

Appends a gdouble as an object.

`self` : | a TrackerSparqlBuilder
`literal` : | object as gdouble

Since 0.8

### tracker_sparql_builder_object_variable ()

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

### Warning

`tracker_sparql_builder_object_variable` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_variable()` in libtracker-sparql instead.

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

`self` : | a TrackerSparqlBuilder
`var_name` : | variable name, without leading '?'

Since 0.8

### tracker_sparql_builder_object_blank_open ()

    void                tracker_sparql_builder_object_blank_open
                                                            (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_object_blank_open` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_blank_open()` in libtracker-sparql instead.

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.

`self` : | a TrackerSparqlBuilder

Since 0.8

### tracker_sparql_builder_object_blank_close ()

    void                tracker_sparql_builder_object_blank_close
                                                            (TrackerSparqlBuilder *self);

### Warning

`tracker_sparql_builder_object_blank_close` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_blank_close()` in libtracker-sparql instead.

Closes an anomymous blank node opened with `tracker_sparql_builder_object_blank_open()`

`self` : | a TrackerSparqlBuilder

Since 0.8

### tracker_sparql_builder_object_unvalidated ()

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

### Warning

`tracker_sparql_builder_object_unvalidated` has been deprecated since version 0.10 and should not be used in newly-written code. Use `tracker_sparql_builder_object_unvalidated()` in libtracker-sparql instead.

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

`self` : | a TrackerSparqlBuilder
`value` : | possibly UTF-8 invalid string.

Since 0.8