Toko – A Commandline Tool for the Triplestore

Download

Toko (short for Tokoeka, the type of Kiwi) is a simple command line tool for interacting with the KiWi triplestore. It supports the following modes/operations:

All commands acting on an argument (i.e. load, query, loadrules and tosql) takes this argument via the -i-flag.

Flags for specifying database name, host, username, etc. are all equivalent to psql. See below for details or further below for examples.

Only SPARQL SELECT-queries are supported, with support for CONSTUCT and DESCRIBE-queries planned for the near future.

Manual

Usage: toko [-vV] [--help] [-B=<baseURI>] [-d=<database>] [-D=<defaultContext>]
            [-h=<host>] [-i=<input>] [-I=<inferredContext>] [-m=<mode>]
            [-P=<password>] [-U=<username>]

DESCRIPTION:
Toko is a simple CLI-program for interacting with the a slight alteration of
the KiWi Triplestore from the Apache Marmotta project.

OPTIONS:
  -B, --baseURI=<baseURI>   The base URI to resolve any relative URIs that
                              occur in the input.
  -d, --database=<database> Which database to connect to. (default: in5800)
  -D, --defaultContext=<defaultContext>
                            The IRI of the default context. default: http:
                              //localhost/context/default)
  -h, --host=<host>         The host containing the database to connect to.
                              (default: localhost)
      --help                Display this help message.
  -i, --input=<input>       The input file path or string to act on.
  -I, --inferredContext=<inferredContext>
                            The IRI of the inferred context. default: http:
                              //localhost/context/inferred)
  -m, --mode=<mode>         The mode of operation to be applied to input.
                            (legal values: load, query, loadrules, init, clean,
                              applymappings, tosql; default: load)
  -P, --password=<password> The password of the user to log in as. (Will be
                              prompted for if not provided and needed.)
  -U, --user=<username>     The username of the user to log in as.
  -v, --verbose             Verbose output. Will display information about what
                              the execution is doing.
  -V, --version             Display version info.

Examples

If we want to initialize a KiWi triplestore in a PostgreSQL database with host dbpg-ifi-kurs01, name in5800, with user leifhka and password pass123, we execute:

java -jar Toko.jar -h dbpg-ifi-kurs01 -d in5800 -U leifhka -P pass123 -v -m init

If we want to load an RDF-file data.ttl into the same triplestore we initialized above, we execute: we execute:

java -jar Toko.jar -h dbpg-ifi-kurs01 -d in5800 -U leifhka -P pass123 -v -m load -i data.ttl

If we want to execute the query SELECT ?s ?p ?o WHERE { ?s ?p ?o . } over the same KiWi triplestore as above, we execute: we execute:

java -jar Toko.jar -h dbpg-ifi-kurs01 -d in5800 -U leifhka -P pass123 -v -m query -i "SELECT ?s ?p ?o WHERE { ?s ?p ?o . }"

Note that the -i-flag expects the query given as a string. If one however wants to execute a query in a file, e.g. q.sparql, one can use cat as follows:

java -jar Toko.jar -h dbpg-ifi-kurs01 -d in5800 -U leifhka -P pass123 -v -m query -i "$(cat q.sparql)"

Direct Mappings

Direct mappings is the most straight forward way of transforming a relational table into an RDF graph. Each row in a table describing an entity becomes its own resource (identified by an IRI) which is typed with a class that denotes the table it comes from. Each attribute/column becomes a property relating each row’s resource to the corresponding value in that column’s row.

Toko maps all tables listed in the table mappings.direct_mappings into the triplestore whenever it executes the applymappings-mode. The mappings.direct_mappings table has the following columns:

mappings.direct_mappings (
    table_schema text NOT NULL,
    table_name text NOT NULL,
    subject_column text,
    context_name text,
    base_uri text NOT NULL
)

where table_schema is the name of the table’s schema, table_name is the table’s name, subject_column denotes which column to use as primary key if the table is in fact a view (this can be NULL for normal tables, as Toko then finds the primary key column itself), context_name is an optional IRI for a context the mapped triples should be put into, and base_uri is the prefix which will be applied to all IRIs made in the mapping process for that table.

IRIs are made accordingly:

If one wants to map a view, this can be done similarly as tables, but one needs to add the name of the identifying column in the subject_column. If there are no single column which values are unique, one can make one by wrapping the view, e.g. V, in another view as follows:

CREATE VIEW V_pk AS
SELECT (row_number() OVER ()) AS id, V.*
FROM V
ORDER BY <column>;

where <columns> are all columns in V. Now id is a column with a unique integer for each row, and can be used as a primary key. One should now rather apply the direct mapping to V_wrapped, and thus insert it’s details into mappings.direct_mappings.

If the view contains references (i.e. foreign keys) to other columns, these needs to be added to the table mappings.view_foreign_keys, which has the following columns:

mappings.view_foreign_keys (
    table_schema text NOT NULL,
    table_name text NOT NULL,
    column_name text NOT NULL,
    foreign_table_schema text NOT NULL,
    foreign_table_name text NOT NULL,
    foreign_column_name text NOT NULL
 )