The Semantic Layer, From ScratchAppendix
Appendix

Glossary

Every term the book introduces, in plain English, with a link to the chapter where it first appears.

Each entry is one or two sentences, written for someone who knows databases well, with a SQL or Java analogy where one helps. Chapter links point to where the term is properly introduced, which is not always its first mention.

A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · X

A

A-Box (Ch. 5): the "assertion box": instance data, such as "customer 225 lives at this address". In SQL terms, the rows rather than the schema.

Agent (Ch. 14): an LLM plus tools plus a loop that calls them until it can answer. Ours has two tools, run_sparql and get_ontology.

Agent loop (Ch. 14): call the model, run the tool calls it requests, append the results, and repeat until it replies with text.

AgentCore (Amazon Bedrock AgentCore) (Ch. 14): AWS's managed service for running agents. Runtime hosts the agent, Gateway authenticates callers and routes tool calls, and Identity holds credentials so agent code never does.

Answer contract (Ch. 16): a fixed JSON shape for an agent's answer, {value, complete, expected, included, missing: [{source, reason}]}, built by code. The agent must repeat its summary verbatim, so "partial" can't get lost in prose.

Apache Calcite (Ch. 14): an open-source framework for optimizing and generating SQL, which Stardog has described using to produce SQL in each database's dialect.

ASK (Ch. 4): a SPARQL query form that returns only true or false, like SELECT EXISTS(…).

Aurora Serverless v2 (Ch. 7): the PostgreSQL service holding the c360 customers, addresses, cards and rewards accounts. It pauses when idle, so the first query after a pause takes 15 to 20 seconds.

B

Axiom (Ch. 5): one statement in the model (T-Box) that the reasoner may use to conclude new facts, such as the subclass axiom :Big_Spender rdfs:subClassOf :Customer or the inverse axiom :placedOrder owl:inverseOf :purchasedBy. Closest SQL idea: a line of schema, except it adds facts instead of rejecting rows, and only with reasoning on.

Big_Spender (Ch. 10): a derived class from the kit's rules: any customer with at least one :Large_Order. It exists only when reasoning is on.

Bind join (Ch. 14): a join that fetches one side first, then sends its keys to the other as a filter (WHERE cid IN (28, 38, …)).

C

Chainlit (Ch. 15): an open-source Python library that gives a chat program a web page: the chat window, collapsible steps, a settings panel, login and a chat-history sidebar. askgraph uses it.

Class (Ch. 5): a named kind of thing, such as :Customer. Closest to a table, except that one thing can belong to many classes, classes nest, and rules can add members later.

Closed-world assumption (Ch. 5): the database habit of treating anything unrecorded as false and rejecting data that doesn't fit the schema. RDF and OWL don't work this way; SHACL lets you check as if they did.

Competency question (Ch. 14): a real business question the semantic layer must answer, written down before you build. The book's five double as the agent's acceptance tests.

Completeness check (Ch. 16): code that compares the sources a metric should include (from the source registry) with the sources that actually contributed, and reports which are missing and why, instead of trusting the LLM to notice.

CONSTRUCT (Ch. 4): a SPARQL query form that returns new triples built from a template instead of rows.

Cooperation without coordination (Ch. 9): the blog's phrase for how federation scales: each team maps its own source, and as long as they mint the same IRIs, the graph joins them with no central integration project.

D

Data contract (Ch. 16): an agreement between a dataset's producers and consumers about its schema, meaning, freshness and change process. A source registry entry is a small data contract.

Data observability (Ch. 16): monitoring data continuously, like services: freshness, volume, schema, distribution and lineage checks (tools such as Monte Carlo and Great Expectations).

Data source (Ch. 7): Stardog's saved connection to an external database (JDBC URL, credentials, options), like a JDBC DataSource. Ours are aurora_c360 and redshift_c360; virtual graphs sit on top of them.

Datatype (Ch. 3): the type attached to a literal, such as xsd:integer or xsd:decimal. It decides how values compare and add up; float instead of decimal cost us two cents in Chapter 9.

Datatype property (Ch. 6): a property whose value is a literal, like :email or :quantity: a plain column. Declared as owl:DatatypeProperty.

Default graph (Ch. 3): the triples in no named graph, and what a query without GRAPH reads. Stardog lets you configure what it includes.

Derived class (Ch. 10): a class whose members a rule computes at query time, such as :Big_Spender, :Large_Order or :2022_Orderer. Like a view that works as a type.

Designer (Ch. 13): Stardog's no-code visual tool for building and publishing ontologies and mappings.

DISTINCT (Ch. 4): removes duplicate result rows, exactly as in SQL.

Domain and range (Ch. 6): rdfs:domain and rdfs:range say what a property starts from and points to. They infer rather than constrain: using the property makes the subject a member of the domain class.

domainIncludes / rangeIncludes (Ch. 6): the schema.org way (so:domainIncludes, so:rangeIncludes) to document which classes a property connects, with no inference. The c360 kit uses them, and Voicebox reads them.

DROP GRAPH (Ch. 4): a SPARQL Update command that deletes a named graph and all its triples; the book uses it to clean up scratch graphs.

E

Egress IP (Ch. 7): the fixed public address Stardog Cloud connects from (44.238.183.206 for our endpoint). The AWS security groups allow only it and your laptop.

Endpoint (Ch. 13): the Stardog server itself, https://<your-endpoint>.stardog.cloud:5820, with its own HTTP API and users; not the Cloud portal.

Explorer (Ch. 13): Stardog's browsing app: search for an entity, view its properties, click through its links.

F

Fallback model (Ch. 15): a second LLM the app switches to when the first one keeps failing, for example openai/gpt-4o-mini after the free model answers 429 twice.

Federation (Ch. 9): answering one query from several sources at once. Stardog splits the SPARQL by source, runs SQL on each, and joins the results itself, copying nothing in advance.

Few-shot examples (Ch. 13, Ch. 16): worked question-and-query pairs shown to an LLM so it copies their patterns. Voicebox takes them from stored queries tagged system:voiceboxQuestion. At scale, the few most similar verified examples are retrieved per question.

FILTER (Ch. 4): a SPARQL condition that drops non-matching results, like a SQL WHERE predicate: FILTER(?total > 10000).

G

Golden test (Ch. 16): a question with an independently verified answer (for us, checked in SQL), rerun automatically against the agent; eval.py.

GRAPH (Ch. 4): the SPARQL keyword that restricts a pattern to one named graph, such as GRAPH <virtual://redshift_c360> { … }. With virtual graphs, it effectively picks the database.

Grounded (Ch. 13): describes an answer whose facts all come from a query against your data (shown alongside it), not from the model's memory.

GROUP BY and aggregates (Ch. 4): as in SQL (COUNT, SUM, AVG, MIN, MAX), except aggregates must be named with AS: (SUM(?price * ?qty) AS ?spend).

Guardrail (Ch. 14): a check your code applies to an LLM's request before acting on it, such as rejecting SPARQL Update or forcing a LIMIT. A second line of defense behind database permissions.

H

Hash join (Ch. 14): a join that loads one side into an in-memory hash table on the join key, then streams the other side past it. One way Stardog joins rows from two sources.

I

Inference: see Reasoning.

INSERT DATA (Ch. 4): a SPARQL Update command that adds literal triples, optionally into a named graph; first used in Chapter 2's scratch exercise.

inverseOf (Ch. 6): owl:inverseOf declares two properties to be the same link read in opposite directions, like :placedOrder and :purchasedBy; with reasoning on, stating one lets you query the other (Java: a bidirectional JPA mappedBy). The kit's schema.ttl has two such axioms, and both are questionable (Chapters 6 and 10).

IRI (Ch. 3): Internationalized Resource Identifier, a globally unique name for a thing or property, such as urn:stardog:demos:c360:customer:225. Like a primary key unique across every database in the world.

IRI template (Ch. 8): a mapping pattern that builds an IRI from column values, such as TEMPLATE("urn:stardog:demos:c360:customer:{cid}"). Two sources using the same template join automatically (Chapter 9's IRI trick).

J

JDBC (Ch. 7): Java Database Connectivity, the standard driver interface Stardog uses to talk to PostgreSQL, Redshift and other SQL databases.

K

Key-overlap probe (key alignment) (Ch. 16): the share of a source's join keys (customer IRIs) that match known entities in the master graph. 0% means the source's IRI template doesn't match, a failure that raises no error.

Knowledge graph (Ch. 1): data as things and the relationships between them, with their meaning described in an ontology. In this book it is mostly virtual: a view over Aurora and Redshift.

Knowledge kit (Ch. 13): an installable package of ontology, rules, mappings, sample data, stored queries and settings, described by kit.yaml. The book started from the c360 training kit.

L

Large_Order (Ch. 10): a derived class from the kit's rules: orders whose unit :purchasePrice exceeds 250 (1,103 of the 2,500). The Big_Spender rule builds on it.

LIMIT (Ch. 4): caps the number of result rows, as in SQL. The Chapter 14 agent forces one on every SELECT.

Literal (Ch. 2): a plain value (string, number, date), as opposed to a thing with an IRI; like a String rather than an object reference. Literals can be objects of triples, never subjects.

LLM (Ch. 13): large language model, such as GPT or Claude. Here its only job is translating between English and SPARQL.

M

Mapping (Ch. 8): a declaration of how SQL rows become triples (which query, which IRIs, which properties), which Stardog runs in reverse to turn SPARQL into SQL. Like JPA annotations, but data rather than code, and each can target a different database.

Materialized graph (Ch. 7): triples copied into Stardog from a source: fast to query, but a copy that goes stale; the ETL-like option.

MCP (Model Context Protocol) (Ch. 13): an open standard for connecting AI hosts to tools: a server advertises tools and a host lets its model call them. Stardog's MCP server exposes Voicebox.

Meaning layer (Ch. 1): the blog's name for the semantic layer, the middle of its three layers (model, meaning, runtime).

Metrics layer (Ch. 16): a place where each business metric is defined once, with its inputs, and reused by every tool: the dbt Semantic Layer (MetricFlow), Cube, Looker's LookML. ops:total_spend ops:requires :Order is the same idea in triples.

N

Named graph (Ch. 3): a set of triples with its own IRI, like a folder or schema. The model lives in <urn:stardog:training-c360:1.0:model>; each virtual graph is one, such as <virtual://aurora_c360_safe>.

Named-graph security (Ch. 12): Stardog's option (security.named.graphs) to grant read access per named graph, so one user sees <virtual://aurora_c360_pii> and another doesn't. Like per-schema grants, across every source.

Native user (Ch. 13): a user defined on the Stardog endpoint, such as stardog_admin. Programs must use one; the portal login doesn't work against the API.

O

Object (Ch. 2): the third part of a triple, the value or thing the arrow points to: an IRI or a literal.

Object property (Ch. 6): a property whose value is another thing (an IRI), like :purchasedBy from an order to a customer: a foreign key column, or a Java reference field. Declared as owl:ObjectProperty.

Ontology (Ch. 5): the formal description of a domain's classes, properties and rules, stored as triples. The c360 ontology has 10 classes, 11 object properties and 22 datatype properties.

Ontology slice (Ch. 16): the few ontology terms a question needs plus their one-hop neighbors, retrieved by search so a huge ontology never has to fit in the prompt.

OpenRouter (Ch. 14): an OpenAI-compatible API (https://openrouter.ai/api/v1) in front of many model providers, with model ids like anthropic/claude-sonnet-4.6.

Open-world assumption (Ch. 5): the RDF/OWL stance that a missing fact is unknown, not false, and that the schema describes rather than rejects.

OPTIONAL (Ch. 4): keeps a result even when part of the pattern has no match, leaving those variables unbound: SPARQL's LEFT OUTER JOIN.

OWL (Ch. 6): the Web Ontology Language, a richer vocabulary than RDFS (owl:Class, owl:ObjectProperty, owl:inverseOf and more) with well-defined reasoning.

P

Path A / Path B (Ch. 14): the blog's two agent designs. Path A gives the LLM a direct SPARQL tool (our agent.py); Path B gives it Voicebox through the Stardog Cloud MCP server.

PII (Ch. 8): personally identifiable information, such as SSNs and card numbers. The book maps it into its own virtual graph, aurora_c360_pii, to lock it down separately.

Portal (Stardog Cloud) (Ch. 13): the website at cloud.stardog.com where you sign in with your email, launch Studio, Designer, Explorer and Voicebox, and manage API keys.

Predicate (Ch. 2): the middle part of a triple, the relationship or attribute name, always an IRI. Roughly a column name.

Prefix (Ch. 3): a short alias for the start of an IRI, like a Java import: after PREFIX : <tag:stardog:api:ecomm:>, :Customer means <tag:stardog:api:ecomm:Customer>.

Prompt caching (Ch. 14): a provider feature that bills a repeated prompt prefix (system prompt, tool definitions) at a discount, as long as it is byte-identical between calls.

Prompt injection (Ch. 14): text in the data or input that tries to give the model instructions. Read-only access limits the damage to a wrong answer.

Provenance / PROV-O (Ch. 16): a record of where a value came from. PROV-O is the W3C vocabulary for it (a Recommendation since 2013): prov:Entity, prov:Activity, prov:Agent, prov:used, prov:wasDerivedFrom.

Pushdown (Ch. 9): sending filters, joins and aggregates into the source SQL so the warehouse does the work and returns fewer rows.

pystardog (Ch. 14): Stardog's official Python client for its HTTP API. The blog's Path A uses it; agent.py calls the same API with requests.

Q

Query planner (Ch. 14): the part of Stardog that decides what goes to which source as SQL, what gets pushed down, and which join strategy to use. Like Hibernate turning JPQL into SQL, but across several databases.

Query rewriting (Ch. 9): Stardog's translation of SPARQL over virtual graphs into SQL for each source, using the mappings in reverse.

R

R2RML (Ch. 8): the W3C standard language for mapping relational tables to RDF. Stardog supports it; the book uses the more compact SMS2.

Rate limit (HTTP 429) (Ch. 15): a provider's cap on requests. A free OpenRouter model allows 50 requests a day without credits; past the cap, or when the provider is busy, it answers 429 "Too Many Requests".

RDF (Ch. 2): Resource Description Framework, the W3C data model in which everything is a triple.

RDFS (Ch. 5): RDF Schema, the basic vocabulary for classes and properties: rdfs:Class, rdfs:subClassOf, rdfs:domain, rdfs:range, rdfs:label, rdfs:comment.

rdfs:label / rdfs:comment (Ch. 5): a human-readable name and description for anything. Studio, Explorer and Voicebox display them, and Voicebox uses them to understand questions.

rdf:type (a) (Ch. 5): the predicate saying what class a thing belongs to, abbreviated a: ?c a :Customer. Like instanceof, except a thing can have many types and a type can be inferred.

Reasoning (inference) (Ch. 10): deriving facts that aren't stored (class membership, inverses, rule results) at query time. In Stardog it is off unless you turn it on for a query.

reasoning.schemas (Ch. 6): the database property naming the graphs that hold the model and rules for reasoning, for example c360_schema=urn:stardog:training-c360:1.0:model.

Role (Ch. 12): a named set of permissions assigned to users, as in SQL. The book creates roles for hr_user and marketing_user.

Rule (Stardog rule) (Ch. 10): an IF { … } THEN { … } statement: with reasoning on, whenever the IF pattern matches, the THEN triples count as true. The kit has five (for example, "big spenders").

S

Schema linking (Ch. 16): matching the words of a question to the right classes and properties (or tables and columns). The hard part of text-to-SQL and text-to-SPARQL on large schemas.

Semantic layer (Ch. 1): a shared, machine-readable model of what your data means, between the sources and the people and agents asking questions: one definition of "big spender" across every system. It is a job, not a technology: this book builds it with a knowledge graph; metrics layers (dbt, Cube), BI-tool models and data virtualization are other ways.

Sensitive property (Ch. 12): a property marked m:SensitiveProperty (the c360 kit marks :ssn and :cardNumber) so Stardog can hide or mask it from users without permission; an alternative to a separate PII graph.

SHACL (Ch. 11): the Shapes Constraint Language, a W3C standard for validating RDF data. It brings closed-world checks (NOT NULL, CHECK, FK-like) to an open-world graph.

Shape (Ch. 11): a SHACL definition of valid data for some target (such as every :Customer), with constraints like sh:minCount and sh:datatype.

SL reasoning (Ch. 10): Stardog's default reasoning level, covering RDFS, most of OWL 2 and user-defined rules, chosen to stay fast at query time.

SMS2 (Ch. 8): Stardog Mapping Syntax 2, a compact SPARQL-like mapping language (MAPPING … FROM SQL { … } TO { … } WHERE { … }), selected with mappings.syntax=SMS2.

Source registry (Ch. 16): triples in <urn:c360:registry> saying which sources provide which classes (ops:provides), how they join (ops:joinsOn), and which classes each metric requires (ops:requires).

SPARQL (Ch. 4): the W3C query language for RDF: you write triple patterns with variables, and Stardog finds every match.

SPARQL Update (Ch. 4): the write half of SPARQL: INSERT, DELETE, DROP, CLEAR, LOAD, CREATE, ADD, MOVE, COPY. The agent rejects all of them.

sql.schemas (Ch. 7): a data source option listing which SQL schemas Stardog may see. Without sql.schemas=c360, mappings fail with "Object 'customer' not found".

Stardog Cloud (Ch. 13): Stardog's hosted service. The book uses the Free tier, which allows up to three databases.

Stored query (Ch. 13): a named SPARQL query saved on the server with metadata; like a JPA @NamedQuery, but shared by every tool. Shared ones tagged system:voiceboxQuestion teach Voicebox.

Strands Agents (Ch. 14): AWS's open-source Python agent framework, which provides the tool loop for the blog's Path A.

Studio (Ch. 13): Stardog's web IDE for queries, data loading, models, virtual graphs and security, used from Chapter 2 on.

subClassOf (Ch. 5): rdfs:subClassOf says every member of one class is also in another (every :Big_Spender is a :Customer); with reasoning on, queries for the parent include the children.

Subject (Ch. 2): the first part of a triple, the thing the statement is about: an IRI (or a blank node), never a literal.

System prompt (Ch. 14): instructions sent to an LLM ahead of the user's message on every call. Ours holds a compact ontology summary, graph names, a worked example and rules.

T

T-Box (Ch. 5): the "terminology box": schema-level triples about classes and properties. The ontology is the T-Box; the data is the A-Box.

Three layers (Ch. 1): the blog's architecture: model (the LLM), meaning (the semantic layer) and runtime (AgentCore, or your laptop in Chapter 14).

Tool call (Ch. 14): one structured request from the model to run a tool: a name plus JSON arguments, such as run_sparql with {"query": "SELECT …"}. Your code returns the result as a tool message.

Tool calling (Ch. 14): the LLM feature (OpenAI's "function calling") that lets a model ask your code to run a named tool; in Java, LangChain4j's @Tool.

Triple (Ch. 2): the atom of RDF, one statement of subject, predicate, object: customer:225 :firstName "Carolyn".

Triple pattern (Ch. 4): a triple with variables in some positions, such as ?c :address ?a. A SPARQL query is a set of them to match.

Turtle (Ch. 3): the most readable text format for RDF (.ttl), with prefixes, ; to repeat the subject, , to repeat the predicate, and a for rdf:type.

U

URN (Ch. 3): a Uniform Resource Name, an IRI that names something without implying a web address, like urn:stardog:demos:c360:customer:225. tag: IRIs (tag:stardog:api:ecomm:) serve the same purpose.

User (Ch. 12): an account on the Stardog endpoint with a password and roles. The agent should run as a read-only user without PII access.

V

Validation report (Ch. 11): a SHACL validation result: whether the data conforms and, for each violation, the offending node, property and constraint.

Variable (Ch. 4): a placeholder name starting with ? for a value you don't know yet; Stardog fills it in from the matching triples, and it becomes a column in the results. In customer:225 :address ?home . ?home :city ?city, ?city comes back as "Milwaukee". A variable shared by two lines works like a JOIN condition.

Virtual graph (Ch. 7): a named graph whose triples are computed on demand from an external database through a mapping, not stored. Ours are aurora_c360_safe, aurora_c360_pii and redshift_c360, queried as <virtual://name>.

Virtual transparency (Ch. 14): the database option virtual.transparency which, with query.all.graphs, lets a query omit GRAPH <virtual://…> and have Stardog route each pattern itself. Off by default.

Voicebox (Ch. 13): Stardog's natural-language interface: an LLM that writes SPARQL from your ontology, search index and stored-query examples, then answers with the query shown.

X

xsd (Ch. 3): the prefix for XML Schema datatypes (http://www.w3.org/2001/XMLSchema#) such as xsd:string, xsd:integer, xsd:decimal, xsd:date, xsd:float, also usable as casts: xsd:decimal(?price).