What this is
tarka turns tables into RDF. A CSV file, a Parquet or Arrow file, or a Polars data frame goes in; a knowledge graph comes out, shaped by a mapping you write in one of three languages: a TARQL query, a set of OTTR templates, or a bOTTR mapping file. It runs as a command, tarka, and as a Python package, tarka-rdf, and it is built on HOLOS, whose SPARQL engine evaluates every query.
This manual teaches all of it, from a first five-line mapping to a pipeline that checks its own output, on one dataset throughout: the Bookshop Trail, a fictional network of independent bookshops at real British places. It is the dataset of the Semantechs SPARQL, SHACL and Ontology courses, with its ontology. The trail committee keeps its records in spreadsheets; by the end of the manual, those spreadsheets have become the courses' graph, triple for triple, and you have proved it.
The name is a nod to Henry Williamson's Tarka the Otter, who lived in "the country of the two rivers". tarka lives where two ways of making RDF meet: TARQL, and OTTR, which is said "otter".
Who it is for
- Data engineers with tables to publish as a knowledge graph, who know SQL and Python and have met RDF.
- Ontologists and modellers who own the vocabulary and want to see it filled, and checked, the way they meant it.
- Anyone running a semantic practice: the manual connects to the SemOps Manual, whose Chapter 10 puts tarka in the ingest stage of a pipeline, and to the Ontology Quality Suite that assesses what it produces.
You need to read a little SPARQL and Turtle. Nothing else is assumed; OTTR is taught from the start.
How to read it
Part I sets out: what tarka does, how to install it, and the trail. Then take the parts in order, or go straight to the one you need:
| Part | Read it to | Chapters |
|---|---|---|
| I. Setting out | know what tarka does, install it, and meet the trail and its spreadsheets | 1, 2, 3 |
| II. TARQL | map a spreadsheet with a SPARQL CONSTRUCT query, simply and then in depth |
4, 5 |
| III. OTTR | build a library of templates, run it over tables and instance files, and map with bOTTR | 6, 7, 8 |
| IV. Data frames | prepare tables with Polars and map frames and Parquet from Python | 9 |
| V. Checking the transformation | prove the RDF is right: SHACL, SPARQL, and the Ontology Quality Suite | 10, 11, 12 |
| VI. In production | load a store, and run the whole thing as a pipeline | 13, 14 |
| Appendices | look something up | A commands, B Python, C differences, D troubleshooting, E the example files |
Run it yourself
Every command and every output in this manual comes from the files in examples/bookshop-trail/, and one script runs them all, in the order the chapters give them, and checks each result:
cd manual/examples/bookshop-trail
python check.py
If a chapter and the script ever disagree, the script is right, and the chapter is a bug.
Editions
The manual is written in Markdown, one file per chapter, and built three ways from the same source: the web edition at https://www.semantechs.co.uk/tarka_Manual/, an EPUB for e-readers, and an A4 PDF for print, both attached to each release. tools/ builds them; see its README.
This edition describes tarka 0.3.1. It was checked with HOLOS (holosdb 0.27.0), SHACL_Engine (shacl 0.3.9), Polars 2.1.0 and the Ontology Quality Suite 0.27.0.