Tarql: SPARQL for Tables
Tarql is a command-line tool for converting CSV files to RDF using SPARQL 1.1 syntax. It’s written in Java and based on Apache ARQ.
Introduction
In Tarql, the following SPARQL query:
is equivalent to executing the following over an empty graph:
In other words, the CSV file’s contents are input into the query as a table of bindings. This allows manipulation of CSV data using the full power of SPARQL 1.1 syntax, and in particular the generation of RDF using CONSTRUCT
queries. See below for more examples.
Command line
For Unix, the executable script is bin/tarql
. For Windows, bin\tarql.bat
. Example invocations:
tarql --help
to show full command line helptarql my_mapping.sparql input1.csv input2.csv
to translate two CSV files using the same mappingtarql --no-header-row my_mapping.sparql input1.csv
if CSV file doesn’t have column headers; variables will be called?a
,?b
, etc.tarql my_mapping.sparql
to translate a CSV file defined in SPARQLFROM
clausetarql --test my_mapping.sparql
to show only the CONSTRUCT template, variable names, and a few input rows (useful for CONSTRUCT query development)`tarql --tabs my_mapping.sparql input.tsv
to read a tab-separated (TSV) file
Full options:
Details
Input CSV file(s) can be specified using FROM
or on the command line. Use FROM <file:filename.csv>
to load a file from the current directory.
Variables: By default, Tarql assumes that the CSV file has column names in the first row, and it will use those column names as variable names. If the file has no header row (indicated via -H
on the command line, or by appending #header=absent
to the CSV file’s URL), then ?a
will contain values from the first column, ?b
from the second, and so on.
All-empty rows are skipped automatically.
Syntactically, a Tarql mapping is one of the following:
- A SPARQL 1.1 SELECT query
- A SPARQL 1.1 ASK query
- One or more consecutive SPARQL 1.1 CONSTRUCT queries, where
PREFIX
andBASE
apply to any subsequent query
In Tarql mappings with multiple CONSTRUCT
queries, the triples generated by previous CONSTRUCT
clauses can be queried in subsequent WHERE clauses to retrieve additional data. When using this capability, note that the order of OPTIONAL
and BIND
is significant in a SPARQL query.
Tarql supports a magic ?ROWNUM
variable for accessing the number of the row within the input CSV file. Numbering starts at 1, and skips empty rows.
Special SPARQL functions: Tarql defines two non-standard SPARQL functions: tarql:expandPrefix(?prefix)
expands any prefixes declared in the Tarql query to their namespace form (as a string). tarql:expandPrefixedName(?qname)
expands a prefixed name such as dc:title
to a full IRI, using any prefixes declared in the Tarql query.
Header row, delimiters, quotes and character encoding in CSV/TSV files
CSV and TSV files vary in details such as the characters used for quoting and escaping, or the character encoding. Information about the input file to guide Tarql’s parsing can be provided in two ways:
- As command line options (e.g.,
--no-header-row
,--tabs
, –encoding`) - As a pseudo-fragment appended to the file’s URL in the
FROM
clause or on the command line (e.g.,file.csv#header=absent;delimiter=tab
)
The following syntax options can be adjusted:
Header row with column names
Presence or absence of a header row with column names to be used as variable names.
- Default: header present
- Command line options:
--no-header-row
,--header-row
- URL:
header=absent
,header=present
Delimiter character
The character used to separate fields in a row; typically comma (default), tab, or semicolon.
- Default: tab for file extension
.tsv
; comma otherwise - Command line options:
--tabs
,--delimiter x
- URL:
delimiter=x
- Recognized values:
comma
,tab
,semicolon
, any single character
Quote character
The character used to enclose field values where the delimiter or a line break occurs within the value; typically, double or single quote. Note that the quote character can be escaped as two consecutive quotes.
- Default: double quote (CSV) or none (TSV)
- Command line option:
--quotechar x
- URL:
quotechar=x
- Recognized values:
none
,singlequote
,doublequote
, any single character
Escape character
The character used to escape quotes occurring within quoted values; typically none or backslash.
- Default: none
- Command line option:
--escapechar x
- URL:
escapechar=x
- Recognized values:
none
,backslash
, any single character
Character encoding
The character encoding of the input file. utf-8
, latin1
, etc.
- Default: attempt to auto-detect
- Command line option:
--encoding xxx
- URL:
encoding=xxx
Design patterns and examples
List the content of the file, projecting the first 100 rows and only the ?id and ?name bindings
Skip bad rows
Skip bad values for a field
Compute additional columns
CONSTRUCT an RDF graph
Generate URIs based on the row number
Count the number of triples from a csv file
Split a field value into multiple values
To split the values of column ?Colors
into multiple values ?Color
on spaces, using Jena’s apf:strSplit
property function. The apf:
prefix is automatically pre-defined.
Provide CSV file encoding and header information in the URL
This is equivalent to using <file.csv>
in the FROM
clause and specifying --no-header-row
and --encoding
on the command line.
Legacy convention for header row
Earlier versions of Tarql had --no-header-row
/#header=absent
as the default, and required the use of a convention to enable the header row:
Here, the OFFSET 1
is a convention that indicates that the first row is to be used to provide variable names, and not as data. This convention is still supported, but will only be recognized if none of the header-specifying command line options or URL fragment arguments are used.
Last Update: May 03, 2019