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


<!-- ##### SECTION Image ##### -->


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

@void: 
@Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
@Deprecated: 0.10: Use tracker_sparql_builder_new() in libtracker-sparql instead.
@Since: 0.8


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

@void: 
@Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
@Deprecated: 0.10: Use tracker_sparql_builder_new_embedded_insert() in libtracker-sparql instead.
@Since: 0.8


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

@void: 
@Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
@Deprecated: 0.10: Use tracker_sparql_builder_new_update() in libtracker-sparql instead.
@Since: 0.8


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

</para>

@object_type: 
@Returns: 
@Deprecated: 0.10: Use tracker_sparql_builder_construct() in libtracker-sparql instead.
@Since: 0.8


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

</para>

@object_type: 
@Returns: 
@Deprecated: 0.10: Use tracker_sparql_builder_construct_embedded_insert() in libtracker-sparql instead.
@Since: 0.8


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

</para>

@object_type: 
@Returns: 
@Deprecated: 0.10: Use tracker_sparql_builder_construct_update() in libtracker-sparql instead.
@Since: 0.8


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

</para>

@self: 
@Returns: 
@Deprecated: 0.10: Use tracker_sparql_builder_get_state() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@Returns: The created SparQL query.
@Deprecated: 0.10: Use tracker_sparql_builder_get_result() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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.
@Deprecated: 0.10: Use tracker_sparql_builder_get_length() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@raw: raw content to append.
@Deprecated: 0.10: Use tracker_sparql_builder_append() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@raw: raw content to prepend.
@Deprecated: 0.10: Use tracker_sparql_builder_prepend() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@graph: Graph name, or %NULL.
@Deprecated: 0.10: Use tracker_sparql_builder_insert_open() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@Deprecated: 0.10: Use tracker_sparql_builder_insert_close() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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
@Deprecated: 0.10: Use tracker_sparql_builder_where_open() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@Deprecated: 0.10: Use tracker_sparql_builder_where_close() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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.
@Deprecated: 0.10: Use tracker_sparql_builder_delete_open() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@Deprecated: 0.10: Use tracker_sparql_builder_delete_close() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@iri: a graph name.
@Deprecated: 0.10: Use tracker_sparql_builder_drop_graph() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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 '?'
@Deprecated: 0.10: Use tracker_sparql_builder_subject_variable() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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.
@Deprecated: 0.10: Use tracker_sparql_builder_subject_iri() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@s: subject string
@Deprecated: 0.10: Use tracker_sparql_builder_subject() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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.
@Deprecated: 0.10: Use tracker_sparql_builder_predicate_iri() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@s: predicate string
@Deprecated: 0.10: Use tracker_sparql_builder_predicate() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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.
@Deprecated: 0.10: Use tracker_sparql_builder_object_iri() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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
@Deprecated: 0.10: Use tracker_sparql_builder_object() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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
@Deprecated: 0.10: Use tracker_sparql_builder_object_string() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@literal: boolean object
@Deprecated: 0.10: Use tracker_sparql_builder_object_boolean() in libtracker-sparql instead.
@Since: 0.8


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

@self: a #TrackerSparqlBuilder
@literal: object as gint64
@Deprecated: 0.10: Use tracker_sparql_builder_object_int64() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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
@Deprecated: 0.10: Use tracker_sparql_builder_object_date() in libtracker-sparql instead.
@Since: 0.8


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

@self: a TrackerSparqlBuilder
@literal: object as #gdouble
@Deprecated: 0.10: Use tracker_sparql_builder_object_double() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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 '?'
@Deprecated: 0.10: Use tracker_sparql_builder_object_variable() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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
@Deprecated: 0.10: Use tracker_sparql_builder_object_blank_open() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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
@Deprecated: 0.10: Use tracker_sparql_builder_object_blank_close() in libtracker-sparql instead.
@Since: 0.8


<!-- ##### 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.
@Deprecated: 0.10: Use tracker_sparql_builder_object_unvalidated() in libtracker-sparql instead.
@Since: 0.8


