Tracker SPARQL Library Reference Manual: TrackerSparqlBuilder

## TrackerSparqlBuilder TrackerSparqlBuilder — Creating insertion/update SPARQL queries. |

## Stability Level

Stable, unless otherwise indicated

## Functions

TrackerSparqlBuilder * | tracker_sparql_builder_new ()
TrackerSparqlBuilder * | tracker_sparql_builder_new_embedded_insert ()
TrackerSparqlBuilder * | tracker_sparql_builder_new_update ()
TrackerSparqlBuilderState | tracker_sparql_builder_get_state ()
const gchar * | tracker_sparql_builder_get_result ()
gint | tracker_sparql_builder_get_length ()
void | tracker_sparql_builder_append ()
void | tracker_sparql_builder_prepend ()
void | tracker_sparql_builder_insert_open ()
void | tracker_sparql_builder_insert_silent_open ()
void | tracker_sparql_builder_insert_close ()
void | tracker_sparql_builder_where_open ()
void | tracker_sparql_builder_where_close ()
void | tracker_sparql_builder_delete_open ()
void | tracker_sparql_builder_delete_close ()
void | tracker_sparql_builder_graph_open ()
void | tracker_sparql_builder_graph_close ()
void | tracker_sparql_builder_subject_variable ()
void | tracker_sparql_builder_subject_iri ()
void | tracker_sparql_builder_subject ()
void | tracker_sparql_builder_predicate_iri ()
void | tracker_sparql_builder_predicate ()
void | tracker_sparql_builder_object_iri ()
void | tracker_sparql_builder_object ()
void | tracker_sparql_builder_object_string ()
void | tracker_sparql_builder_object_boolean ()
void | tracker_sparql_builder_object_int64 ()
void | tracker_sparql_builder_object_date ()
void | tracker_sparql_builder_object_double ()
void | tracker_sparql_builder_object_variable ()
void | tracker_sparql_builder_object_blank_open ()
void | tracker_sparql_builder_object_blank_close ()
void | tracker_sparql_builder_object_unvalidated ()

## Properties

gint | length | Read
gchar * | result | Read
TrackerSparqlBuilderState | state | Read

## Types and Values

struct | TrackerSparqlBuilder
enum | TrackerSparqlBuilderState

## Object Hierarchy

        GEnum
        ╰── TrackerSparqlBuilderState
        GObject
        ╰── TrackerSparqlBuilder

## Includes

    #include <tracker-sparql.h>

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

## Functions

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

self | a TrackerSparqlBuilder |

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.

#### Parameters

self | a TrackerSparqlBuilder |

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

#### Parameters

self | a TrackerSparqlBuilder |

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.

#### Parameters

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

#### Parameters

self | a TrackerSparqlBuilder |

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.

#### Parameters

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

#### Parameters

self | a TrackerSparqlBuilder |

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

self | a TrackerSparqlBuilder |

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

#### Parameters

self | a TrackerSparqlBuilder |

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.

#### Parameters

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

Since 0.10

## Types and Values

### struct TrackerSparqlBuilder

    struct TrackerSparqlBuilder;

The TrackerSparqlBuilder object represents an insertion/update SPARQL query.

### enum TrackerSparqlBuilderState

Enumeration with the possible states of the SPARQL Builder

#### Members

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 |

## Property Details

### The `“length”` property

      “length”                   gint

Number of objects added to the TrackerSparqlBuilder.

Flags: Read

Default value: 0

Since 0.10

### The `“result”` property

      “result”                   gchar *

String containing the constructed SPARQL in the TrackerSparqlBuilder.

Flags: Read

Default value: NULL

Since 0.10

### The `“state”` property

      “state”                    TrackerSparqlBuilderState

Current state of the TrackerSparqlBuilder.

Flags: Read

Default value: TRACKER_SPARQL_BUILDER_STATE_UPDATE

Since 0.10