<!-- ##### SECTION Title ##### -->
Sparql builder

<!-- ##### SECTION Short_Description ##### -->
Creating insertion/update SparQL queries.

<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>

<para>
When using #TrackerSparqlBuilder, note that you may append several predicates
for the same subject, and several objects for the same predicate.
</para>

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

<!-- ##### SECTION See_Also ##### -->
<para>
</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT TrackerSparqlBuilder ##### -->
<para>
The <structname>TrackerSparqlBuilder</structname> object represents an
insertion/update SparQL query.
</para>

@parent_instance: 
@priv: 

<!-- ##### STRUCT TrackerSparqlBuilderClass ##### -->
<para>

</para>

@parent_class: 

<!-- ##### STRUCT TrackerSparqlBuilderPrivate ##### -->
<para>

</para>


<!-- ##### ENUM TrackerSparqlBuilderState ##### -->
<para>

</para>

@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: 

<!-- ##### FUNCTION tracker_sparql_builder_new ##### -->
<para>
Creates a stateless #TrackerSparqlBuilder.
</para>

@Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done


<!-- ##### FUNCTION tracker_sparql_builder_new_embedded_insert ##### -->
<para>
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.
</para>

@Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done


<!-- ##### FUNCTION tracker_sparql_builder_new_update ##### -->
<para>
Creates an empty #TrackerSparqlBuilder for an update query.
</para>

@Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done


<!-- ##### FUNCTION tracker_sparql_builder_construct ##### -->
<para>

</para>

@object_type: 
@Returns: 


<!-- ##### FUNCTION tracker_sparql_builder_construct_embedded_insert ##### -->
<para>

</para>

@object_type: 
@Returns: 


<!-- ##### FUNCTION tracker_sparql_builder_construct_update ##### -->
<para>

</para>

@object_type: 
@Returns: 


<!-- ##### FUNCTION tracker_sparql_builder_get_state ##### -->
<para>

</para>

@self: 
@Returns: 


<!-- ##### FUNCTION tracker_sparql_builder_get_result ##### -->
<para>
Returns the constructed SparQL query as a string.
</para>

@self: a #TrackerSparqlBuilder
@Returns: The created SparQL query.


<!-- ##### FUNCTION tracker_sparql_builder_get_length ##### -->
<para>
Returns the number of objects added to @self.
</para>

@self: a #TrackerSparqlBuilder
@Returns: The number of objects contained.


<!-- ##### FUNCTION tracker_sparql_builder_append ##### -->
<para>
Appends raw, unvalidated content to @self.
</para>

@self: a #TrackerSparqlBuilder
@raw: raw content to append.


<!-- ##### FUNCTION tracker_sparql_builder_prepend ##### -->
<para>
Prepends raw, unvalidated content to @self.
</para>

@self: a #TrackerSparqlBuilder
@raw: raw content to prepend.


<!-- ##### FUNCTION tracker_sparql_builder_insert_open ##### -->
<para>
Opens an insertion statement.
</para>

@self: a #TrackerSparqlBuilder
@graph: Graph name, or %NULL.


<!-- ##### FUNCTION tracker_sparql_builder_insert_close ##### -->
<para>
Closes an insertion statement opened with tracker_sparql_builder_insert_open ().
</para>

@self: a #TrackerSparqlBuilder


<!-- ##### FUNCTION tracker_sparql_builder_where_open ##### -->
<para>
Opens a WHERE clause. Data triples may be appended then to narrow the scope
to which the update query applies.
</para>

@self: a #TrackerSparqlBuilder


<!-- ##### FUNCTION tracker_sparql_builder_where_close ##### -->
<para>
Closes a WHERE clause opened through tracker_sparql_builder_where_open().
</para>

@self: a #TrackerSparqlBuilder


<!-- ##### FUNCTION tracker_sparql_builder_delete_open ##### -->
<para>
Opens a DELETE clause. Data triples may be appended in order to prepare
a query to delete them.
</para>

@self: a #TrackerSparqlBuilder
@graph: Graph name, or %NULL.


<!-- ##### FUNCTION tracker_sparql_builder_delete_close ##### -->
<para>
Closes a DELETE clause opened through tracker_sparql_builder_delete_close().
</para>

@self: a #TrackerSparqlBuilder


<!-- ##### FUNCTION tracker_sparql_builder_drop_graph ##### -->
<para>
Appends a DROP GRAPH clause.
</para>

@self: a #TrackerSparqlBuilder
@iri: a graph name.


<!-- ##### FUNCTION tracker_sparql_builder_subject_variable ##### -->
<para>
Appends a subject as a SparQL variable, such as "?urn".
</para>

@self: a #TrackerSparqlBuilder
@var_name: Variable name, without leading '?'


<!-- ##### FUNCTION tracker_sparql_builder_subject_iri ##### -->
<para>
Appends a subject as an IRI, such as "&lt;urn:file:1234-5678&gt;". IRIs
univocally identify a resource in tracker-store.
</para>

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


<!-- ##### FUNCTION tracker_sparql_builder_subject ##### -->
<para>
Appends a subject.
</para>

@self: a #TrackerSparqlBuilder
@s: subject string


<!-- ##### FUNCTION tracker_sparql_builder_predicate_iri ##### -->
<para>
Appends a predicate as an IRI.
</para>

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


<!-- ##### FUNCTION tracker_sparql_builder_predicate ##### -->
<para>
Appends a predicate for the previously appended subject.
</para>

@self: a #TrackerSparqlBuilder
@s: predicate string


<!-- ##### FUNCTION tracker_sparql_builder_object_iri ##### -->
<para>
Appends an object as an IRI.
</para>

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


<!-- ##### FUNCTION tracker_sparql_builder_object ##### -->
<para>
Appends a free-form object for the previously appended subject and predicate.
</para>

@self: a #TrackerSparqlBuilder
@s: object string


<!-- ##### FUNCTION tracker_sparql_builder_object_string ##### -->
<para>
Appends an object formatted as an string. @literal will be escaped and surrounded
by double quotes.
</para>

@self: a #TrackerSparqlBuilder
@literal: string object


<!-- ##### FUNCTION tracker_sparql_builder_object_boolean ##### -->
<para>
Appends a #gboolean value as an object.
</para>

@self: a #TrackerSparqlBuilder
@literal: boolean object


<!-- ##### FUNCTION tracker_sparql_builder_object_int64 ##### -->
<para>
Appends a #gint64 as an object.
</para>

@self: a #TrackerSparqlBuilder
@literal: object as gint64


<!-- ##### FUNCTION tracker_sparql_builder_object_date ##### -->
<para>
Appends a time_t as an object. @literal will be converted to a
string in the date format used by tracker-store.
</para>

@self: a #TrackerSparqlBuilder
@literal: object as time_t


<!-- ##### FUNCTION tracker_sparql_builder_object_double ##### -->
<para>
Appends a #gdouble as an object.
</para>

@self: a TrackerSparqlBuilder
@literal: object as #gdouble


<!-- ##### FUNCTION tracker_sparql_builder_object_variable ##### -->
<para>
Appends an object as a SparQL variable, such as "?urn".
</para>

@self: a #TrackerSparqlBuilder
@var_name: variable name, without leading '?'


<!-- ##### FUNCTION tracker_sparql_builder_object_blank_open ##### -->
<para>
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.
</para>

@self: a #TrackerSparqlBuilder


<!-- ##### FUNCTION tracker_sparql_builder_object_blank_close ##### -->
<para>
Closes an anomymous blank node opened with tracker_sparql_builder_object_blank_open()
</para>

@self: a #TrackerSparqlBuilder


<!-- ##### FUNCTION tracker_sparql_builder_object_unvalidated ##### -->
<para>
Appends a string not validated as UTF-8 as an object.
</para>

@self: a #TrackerSparqlBuilder
@value: possibly UTF-8 invalid string.


