# 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 Write operations, you must get the connection object with `tracker_sparql_connection_get`.

- D-Bus FD passing:

  The TrackerSparqlConnection will use the File Descriptor passing method via D-Bus to connect to the Store for all non Read-Only queries on TrackerSparqlConnection objects obtained with `tracker_sparql_connection_get`.

  See the Environment Variables section to check how you can force also Read-Only queries to be done using D-Bus.

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

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.12` 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_USE_LOG_FILES

  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.

- TRACKER_USE_CONFIG_FILES

  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/

- 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_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.