1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
<?xml version='1.0' encoding="ISO-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
]>
<part id="tracker-examples">
<title>Examples</title>
<partintro>
<para>
This chapters shows some real examples of usage of the Tracker SPARQL Library.
</para>
</partintro>
<chapter id="tracker-examples-readonly">
<title>Querying the Store</title>
<para>
First, a <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
object must be acquired with
<function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
Then, a query can be launched either synchronously (<function><link linkend="tracker-sparql-connection-query">tracker_sparql_connection_query</link></function>)
or asynchronously (<function><link linkend="tracker-sparql-connection-query-async">tracker_sparql_connection_query_async</link></function>).
If launched asynchronously, the results of the query can be obtained with
<function><link linkend="tracker-sparql-connection-query-finish">tracker_sparql_connection_query_finish</link></function>.
</para>
<para>
If the query was successful, a <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type>
will be available. You can now iterate the results of the query both synchronously (with
<function><link linkend="tracker-sparql-cursor-next">tracker_sparql_cursor_next</link></function>) or
asynchronously (with
<function><link linkend="tracker-sparql-cursor-next-async">tracker_sparql_cursor_next_async</link></function> and
<function><link linkend="tracker-sparql-cursor-next-finish">tracker_sparql_cursor_next_finish</link></function>)
</para>
<para>
The <function><link linkend="tracker-sparql-connection-query-statement">tracker_sparql_connection_query_statement</link></function>
function can be used to obtain a <link linkend="TrackerSparqlStatement">TrackerSparqlStatement</link> object holding a prepared SPARQL
query that can then be executed with <function><link linkend="tracker-sparql-statement-execute">tracker_sparql_statement_execute</link>.
The query string can contain <systemitem>~name</systemitem> placeholders which can be replaced with arbitrary values before query execution with the
<function><link linkend="tracker-sparql-statement-bind-string">tracker_sparql_statement_bind_string</link> and similar functions.
This allows parsing the query string only once and to execute it multiple times with different parameters with potentially significant performance gains.
</para>
<para>
The following program shows how Read-Only queries can be done to the store in a
synchronous way:
<informalexample>
<programlisting language="C">
<xi:include href="readonly-example.c" parse="text"/>
</programlisting>
</informalexample>
</para>
</chapter>
<chapter id="tracker-examples-writeonly">
<title>Updating the Store</title>
<para>
In order to perform updates in the store, a new
<type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
object must be acquired with
<function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
Once a proper connection object has been acquired, the update can be launched either
synchronously (<function><link linkend="tracker-sparql-connection-update">tracker_sparql_connection_update</link></function>)
or asynchronously (<function><link linkend="tracker-sparql-connection-update-async">tracker_sparql_connection_update_async</link></function>).
If launched asynchronously, the result of the operation can be obtained with
<function><link linkend="tracker-sparql-connection-update-finish">tracker_sparql_connection_update_finish</link></function>.
</para>
<para>
Once you no longer need the connection, remember to call <function><link linkend="g-object-unref">g_object_unref</link></function>
for the <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>.
</para>
<para>
The following program shows how a synchronous update can be done to the store:
<informalexample>
<programlisting language="C">
<xi:include href="writeonly-example.c" parse="text"/>
</programlisting>
</informalexample>
</para>
</chapter>
<chapter id="tracker-examples-writeonly-with-blank-nodes">
<title>Updating the Store with Blank Nodes</title>
<para>
The majority of the work here is already described in the
<link linkend="tracker-examples-writeonly">previous example</link> where we talk about how to write the store.
</para>
<para>
The difference with this example is that sometimes you want to
insert data and have the URNs returned which were created to
avoid re-querying for them. This is done using
the <function><link linkend="tracker-sparql-connection-update-blank">tracker_sparql_connection_update_blank</link></function> function (or asynchronously <function><link linkend="tracker-sparql-connection-update-blank-async">tracker_sparql_connection_update_blank_async</link></function>).
If launched asynchronously, the result of the operation can be obtained with
<function><link linkend="tracker-sparql-connection-update-blank-finish">tracker_sparql_connection_update_blank_finish</link></function>.
</para>
<para>
The <emphasis>_:foo</emphasis> in the example is how a blank node is
represented in SPARQL. The <emphasis>foo</emphasis> part is used to generate the
unique ID that is used for the new URN. It is also used in the
<function><link linkend="GVariant">GVariant</link></function>
that is returned. In the example below, we are creating a new
blank node called <emphasis>foo</emphasis> for every class that
exists.
</para>
<para>
The format of the GVariant (in D-Bus terms) is an aaa{ss} (an
array of an array of dictionaries). This is rather complex but
for a good reason. The first array represents each INSERT that
may exist in the SPARQL. The second array represents each new
node for a given WHERE clause (the example below illustrates
this), you need this to differentiate between two INSERT
statments like the one below in the same SPARQL sent to the
store. Last, we have a final array to represent each new node's
name (in this case <emphasis>foo</emphasis>) and the actual URN which was
created. For most updates the first two outer arrays will only
have one item in them.
</para>
<para>
The following program shows how a synchronous blank node update can be done to the store:
<informalexample>
<programlisting language="C">
<xi:include href="writeonly-with-blank-nodes-example.c" parse="text"/>
</programlisting>
</informalexample>
</para>
</chapter>
</part>
|
