diff options
Diffstat (limited to 'docs/reference/libtracker-sparql/overview.xml')
| -rw-r--r-- | docs/reference/libtracker-sparql/overview.xml | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/docs/reference/libtracker-sparql/overview.xml b/docs/reference/libtracker-sparql/overview.xml new file mode 100644 index 000000000..14890457d --- /dev/null +++ b/docs/reference/libtracker-sparql/overview.xml @@ -0,0 +1,183 @@ +<?xml version='1.0' encoding="ISO-8859-1"?> + +<part id="tracker-overview"> + <title>Overview</title> + <partintro> + <para> + The libtracker-sparql library is the foundation for Tracker + querying and inserting into the data store. The data store + allows both querying and inserting using SPARQL based on the + Nepomuk ontology. + </para> + </partintro> + + + <chapter id="tracker-overview-connection-methods"> + <title>Connection methods</title> + + <para> + The Tracker SPARQL library provides several underlying methods to perform + queries and updates to the Tracker Store. + + <itemizedlist> + <listitem> + <emphasis>Direct Access:</emphasis> + <para> + All Read-Only operations done in a + <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> + will by default use this method, as it doesn't involve any D-Bus traffic, + and thus, it will perform much better. There is no real connection with + the Tracker Store in this case, as the access is direct to the underlying + SQLite database. Again, note that this method applies only to + <emphasis>Read-Only</emphasis> operations. + </para> + <para> + If you plan to only do Read-Only queries to the store, you can get the + <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> + object using <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function>. Otherwise, if you also plan to use the same connection object + for <emphasis>Write</emphasis> operations, you must get the connection object with + <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>. + </para> + </listitem> + <listitem> + <emphasis>D-Bus FD passing:</emphasis> + <para> + The <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> + will use the File Descriptor passing method via D-Bus to connect to the Store for all non + Read-Only queries on + <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> + objects obtained with + <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>. + </para> + <para> + See the <link linkend="tracker-overview-environment-variables">Environment Variables</link> section + to check how you can force also Read-Only queries to be done using D-Bus. + </para> + </listitem> + </itemizedlist> + </para> + </chapter> + + <chapter id="tracker-overview-compiling"> + <title>Compiling applications</title> + + <para> + To compile applications using libtracker-sparql, you + need to tell the compiler where to find the proper header files + and libraries. This is done with the + <application>pkg-config</application> utility. + </para> + + <para> + The following interactive shell session demonstrates how + <application>pkg-config</application> is used (the actual output on + your system may be different): +<programlisting> +$ pkg-config --cflags tracker-sparql-0.12 +-pthread -I/usr/include/tracker-0.12 -I/usr/include/tracker-0.12/libtracker-sparql -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include + +$ pkg-config --libs tracker-sparql-0.12 +-Wl,--export-dynamic -pthread -ltracker-sparql-0.12 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0 +</programlisting> + </para> + <para> + The simplest way to compile a program is to use the "backticks" + feature of the shell. If you enclose a command in backticks + (<emphasis>not single quotes</emphasis>), then its output will be + substituted into the command line before execution: +<programlisting> + $ cc `pkg-config --cflags --libs tracker-sparql-0.12` hello.c -o hello +</programlisting> + </para> + + </chapter> + + <chapter id="tracker-overview-environment-variables"> + <title>Environment Variables</title> + + <para> + There are a number of environment variables which affect the way + that the libtracker-sparql library will do its work. Those + environment variables are described here. + + <itemizedlist> + <listitem> + <emphasis>TRACKER_USE_LOG_FILES</emphasis> + <para> + Don't just log to stdout and stderr, but to log files too + which are kept in $HOME/.local/share/tracker/. This came + into effect in 0.15.3 and 0.16.0. After this version of + Tracker, logging to file (usually useful for debugging) + can only be done by declaring this environment variable. + </para> + </listitem> + <listitem> + <emphasis>TRACKER_USE_CONFIG_FILES</emphasis> + <para> + Don't use GSettings, instead use a config file similar to + how settings were saved in 0.10.x. That is, a file which + is much like an .ini file. These are saved to + $HOME/.config/tracker/ + </para> + </listitem> + <listitem> + <emphasis>TRACKER_SPARQL_BACKEND</emphasis> + <para> + Backends for libtracker-sparql are dynamically loaded at + run time. Currently there are only two backends which are + <link linkend="overview-tracker-connection-methods">explained + more closely</link> in the previous chapter. In short, + this environment variable gives the client the ability to + directly mandate which backend they want to use. The + value can be set to either "direct" or "bus". A "direct" + value means the direct access approach will be forced. A + "bus" value means a D-Bus / IPC approach will be forced. + </para> + </listitem> + <listitem> + <emphasis>TRACKER_SPARQL_CACHE_SIZE</emphasis> + <para> + Tracker caches database statements which occur frequently to make + subsequent repeat queries much faster. The cache size is + set to <emphasis>100</emphasis> by default for each type + (select and update queries). This must be at + least <emphasis>2</emphasis> as a minimum, any less and a + value of <emphasis>3</emphasis> is used instead. The + number represents the number of cached statements to keep + around. This environment variable is used mainly for + testing purposes. + </para> + <para> + Tracker's store also has environment variables to control + this behavior, see the manual pages + for <emphasis>tracker-store</emphasis> + regarding <emphasis>TRACKER_STORE_SELECT_CACHE_SIZE</emphasis> + and <emphasis>TRACKER_STORE_UPDATE_CACHE_SIZE</emphasis>. + </para> + </listitem> + <listitem> + <emphasis>TRACKER_VERBOSITY</emphasis> + <para> + Historically, all queries would go + through <emphasis>tracker-store</emphasis> and all + requests would be logged according to the verbosity set + in <emphasis>tracker-store.cfg</emphasis> (see manual + pages for <emphasis>tracker-store.cfg</emphasis>). Since + libtracker-sparql may + circumvent <emphasis>tracker-store</emphasis> if using the + direct access backend, this environment variable was added + to let clients choose the log level. The same values apply + to all other processes which have logging and a + configuration to control it. Values range + from <emphasis>0</emphasis> to <emphasis>3</emphasis>, + 0=errors, 1=minimal, 2=detailed, 3=debug. By default it + is <emphasis>0</emphasis>. + </para> + </listitem> + </itemizedlist> + </para> + + </chapter> + +</part> + |