← Semantechs home The tarka Manual EPUBA4 PDFGitHub
Contents
  1. Introduction

Part I — Setting out

  1. 1What tarka does
  2. 2Installing
  3. 3The Bookshop Trail

Part II — TARQL

  1. 4A first mapping
  2. 5TARQL in depth

Part III — OTTR

  1. 6Templates
  2. 7OTTR over tables
  3. 8bOTTR

Part IV — Data frames

  1. 9Python and Polars

Part V — Checking the transformation

  1. 10Shapes and SHACL
  2. 11SPARQL checks
  3. 12The Ontology Quality Suite

Part VI — In production

  1. 13Into a store
  2. 14A pipeline

Appendices

  1. ACommand reference
  2. BPython reference
  3. CDifferences
  4. DTroubleshooting
  5. EThe example files

The tarka Manual

From tables to triples along the Bookshop Trail: TARQL queries, OTTR templates and data frames, and how to know the RDF is right.

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.