# Overview

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.

## Connection methods

The Tracker SPARQL library provides several underlying methods to perform queries and updates to the Tracker Store.

- Direct Access:

  All Read-Only operations done in a TrackerSparqlConnection 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 Read-Only operations.

  If you plan to only do Read-Only queries to the store, you can get the TrackerSparqlConnection object using `tracker_sparql_connection_get_direct`. Otherwise, if you also plan to use the same connection object for updates, you must get the connection object with `tracker_sparql_connection_get`.

- D-Bus FD passing:

  If the system runs a D-Bus ≥ 1.3.1, the TrackerSparqlConnection will use the File Descriptor passing method via D-Bus to connect to the Store, which is faster than the plain D-Bus for queries involving a lot of traffic. This method will be used for all non read-only queries on TrackerSparqlConnection objects obtained with `tracker_sparql_connection_get`.

- D-Bus:

  If the system runs a D-Bus < 1.3.1, the TrackerSparqlConnection will use the standard D-Bus method to connect to the Store. This method will be used for all non read-only queries on TrackerSparqlConnection objects obtained with `tracker_sparql_connection_get`.

Please note that the user of the library cannot choose a specific method to be used, as that is done automatically by the TrackerSparqlConnection depending on the available possibilities.

## Compiling applications

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 pkg-config utility.

The following interactive shell session demonstrates how pkg-config is used (the actual output on your system may be different):

    $ pkg-config --cflags tracker-sparql-0.9
     -pthread -I/usr/include/tracker-0.9 -I/usr/include/tracker-0.9/libtracker-sparql -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include

    $ pkg-config --libs tracker-sparql-0.9
     -Wl,--export-dynamic -pthread -ltracker-sparql-0.9 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0

The simplest way to compile a program is to use the "backticks" feature of the shell. If you enclose a command in backticks (not single quotes), then its output will be substituted into the command line before execution:

     $ cc `pkg-config --cflags --libs tracker-sparql-0.9` hello.c -o hello

## Environment Variables

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.

- TRACKER_SPARQL_BACKEND

  Backends for libtracker-sparql are dynamically loaded at run time. Currently there are only two backends which are explained more closely 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.

- TRACKER_SPARQL_MODULE_PATH

  As explained in the last paragraph, the backends are dynamically loaded at run time. The location for these backends is usually in a set place: $prefix/lib/tracker-$version/sparql-modules. This environment variable is mostly useful for the unit tests and general debugging to override this location.

- TRACKER_SPARQL_CACHE_SIZE

  Tracker caches database statements which occur frequently to make subsequent repeat queries much faster. The cache size is set to 100 by default for each type (select and update queries). This must be at least 2 as a minimum, any less and a value of 3 is used instead. The number represents the number of cached statements to keep around. This environment variable is used mainly for testing purposes.

  Tracker's store also has environment variables to control this behavior, see the manual pages for tracker-store regarding TRACKER_STORE_SELECT_CACHE_SIZE and TRACKER_STORE_UPDATE_CACHE_SIZE.

- TRACKER_VERBOSITY

  Historically, all queries would go through tracker-store and all requests would be logged according to the verbosity set in tracker-store.cfg (see manual pages for tracker-store.cfg). Since libtracker-sparql may circumvent tracker-store 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 0 to 3, 0=errors, 1=minimal, 2=detailed, 3=debug. By default it is 0.

- TRACKER_PRAGMAS_FILE

  Tracker has a fixed set of PRAGMA settings for creating its SQLite connection. With this environment variable pointing to a text file you can override these settings. The file is a \n separated list of SQLite queries to execute on any newly created SQLite connection in tracker-store.

- TRACKER_DISABLE_MEEGOTOUCH_LOCALE

  If Tracker is compiled with meegotouch locale management support, setting this variable in the environment will disable retrieving the locale from GConf, and the standard locale settings will be used instead.