Names, values and files

Carolyn Inworth has spent exactly $502,529.42 with us; Redshift says so, to the cent. Now write that number into a graph twice. Label it once as a decimal and once as a float, and read both back. The decimal returns $502,529.42. The float returns $502,529.40625. Same number, same database; the only difference is one word saying what type of value it is, and that one word puts one customer's total two cents off. This chapter is about the unglamorous things that decide whether a knowledge graph is right or almost right: how things are named, how values carry their types, how triples are written in files, and which folder they're kept in.

3.1Names that mean the same thing everywhere

In Aurora, 225 means Carolyn only because it sits in the cid column of c360.customer. In Redshift, product.id = 225 is a product. A key means something only together with its table.

A graph has no tables to supply that context, and triples from different sources mix freely (Figure 2.2). So every thing needs a name that means the same everywhere and can't collide. That's what IRIs are for:

One property of IRIs catches everyone: they're compared as exact strings. …customer:225, …Customer:225 and …customer:0225 are three different things. One stray character and you have a stranger.

3.2Names built from keys: a preview of the IRI trick

Nobody types urn:stardog:demos:c360:customer:225 by hand. It's computed from the row's key by an IRI template: a fixed string with a slot for a column, like urn:stardog:demos:c360:customer:{cid}, so the same row gets the same name every time, from any system (Chapter 8 writes them). Every c360 thing follows one pattern, urn:stardog:demos:c360:<kind>:<key>:

The customer template appears in both databases. Here's the actual line from the Aurora mapping (Chapter 8) and the Redshift mapping (Chapter 9):

# Aurora mapping, c360.customer
BIND(TEMPLATE("urn:stardog:demos:c360:customer:{cid}") AS ?iri)

# Redshift mapping, c360.purchase
BIND(TEMPLATE("urn:stardog:demos:c360:customer:{cid}") AS ?cust_iri)

Both sides produce exactly the same string for Carolyn, and triples that use the same name are about the same node (Section 2.4). The blog calls this the IRI template; this book calls it the IRI trick, and Chapter 9 shows the machinery. For now, notice that it's nothing more than an agreement about spelling.

3.3Values carry their types

The types in c360, with SQL cousins and shorthand:

The type decides how values sort, compare and add up. As strings, "9" sorts after "10", so "top orders by quantity" with a string quantity is wrong in a way that looks almost right. FILTER(?price > 250), the heart of the "large order" rule (Chapter 10), only works if ?price is a number; YEAR(?date) only works on a real date. And then there's arithmetic.

When the data lives in Aurora and Redshift, a value's type comes from the mapping. The ontology can say what type a property is meant to have, but that documents rather than converts (Chapter 6). So the working mappings cast explicitly: xsd:decimal for money, xsd:integer for quantities, xsd:date for dates. Without casts, values arrive with whatever type the database driver reports.

3.4Prefixes: nicknames for namespaces

Typing <tag:stardog:api:ecomm:firstName> every time, as you did in Chapter 2, gets old fast.

Ours is : (also written ecomm:) = tag:stardog:api:ecomm:. The standard ones: rdf: (core terms, chiefly rdf:type), rdfs: (labels, classes; Chapter 5), owl: (richer ontology terms; Chapter 6), xsd: (datatypes) and, in the kit, so: for https://schema.org/. Full namespaces are in the Turtle file in Section 3.7.

Because expansion is pure text, one IRI can have several spellings. The kit's rules file declares stardog: as tag:stardog:api: and writes stardog:ecomm:Customer, which expands to exactly :Customer. Stardog only compares the expanded form.

3.5Turtle: triples in a file

Triples need a file format, the way tables have CSV and SQL dumps. The one people read and write is Turtle (.ttl), a compact text format, because one triple per line with full IRIs is correct but exhausting. The kit's ontology files are Turtle, and so is what Stardog Designer exports. Watch three facts shrink.

Full form, one triple per line, each ending in a full stop. Valid Turtle already:

<urn:stardog:demos:c360:customer:225> <tag:stardog:api:ecomm:firstName> "Carolyn" .
<urn:stardog:demos:c360:customer:225> <tag:stardog:api:ecomm:lastName>  "Inworth" .
<urn:stardog:demos:c360:customer:225> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <tag:stardog:api:ecomm:Customer> .

With prefixes, a semicolon, and a. In a file, prefixes are declared with @prefix and a full stop. A semicolon means "same subject, next predicate". And a is short for rdf:type, the predicate that says what kind of thing something is:

@prefix : <tag:stardog:api:ecomm:> .

<urn:stardog:demos:c360:customer:225> a :Customer ;
    :firstName "Carolyn" ;
    :lastName  "Inworth" .

A comma means "same subject and predicate, another object". This line from the kit's schema.ttl is four triples:

:name so:domainIncludes :Category, :Customer, :Product, :Vendor .

That's enough to read the kit's ontology, which you'll load in Chapter 6. Its opening lines say "Industry is an OWL class labeled 'Industry'", and so on:

:Industry a owl:Class ;
    rdfs:label "Industry" .

:Customer a owl:Class ;
    rdfs:label "Customer" .

# starts a comment (like SQL's --), and whitespace doesn't matter. One trap: SPARQL declares prefixes as PREFIX, with no @ and no full stop, a frequent typo.

3.6Named graphs: folders inside the database

The build uses these folders four ways. Organization: the ontology and the rules each get a graph, so each can be reloaded alone (Chapter 6). Cleanup: DROP GRAPH removes a whole folder. Provenance: each virtual graph has a name like <virtual://redshift_c360>, so a query can say which source it means. Security: access can be granted per graph (Chapter 12).

What does a query see? By default, a Stardog query that doesn't name a graph reads only the default graph. The database option query.all.graphs widens that to all local graphs, and special names such as <tag:stardog:api:context:all> mean "every local and virtual graph" (see Querying Stardog in the docs). This book's habit is simpler: always say which graph you mean, with GRAPH <…> { … }.

3.7Hands-on: a Turtle file in its own folder

You'll write a Turtle file about Carolyn, her address and one of her orders, load it into <urn:book:ch03>, inspect the types, and delete it. Load it from a file with Studio's Load Data dialog (Path A) or by pasting an INSERT DATA (Path B). Do one, not both.