The Stardog toolbox

Here's a puzzle. You paste the federated query from Chapter 9 into Studio, press Run, and there's Carolyn Inworth at the top with $502,529.42. You copy the same query into a five-line Python script, point it at the same database, and log in with the same email and password. The answer: 401 Unauthorized. What changed?

Section 13.2 answers that, and the answer explains how Stardog Cloud is put together. Then we tour the toolbox, including its star, Voicebox, which does for business users what Chapter 14's agent will do for you. Nothing gets built here. The one hands-on step is read-only: ask Voicebox a question and read the SPARQL it writes, which works only because your ontology and virtual graphs (Chapters 6 to 9) are in place.

13.1Terms in this chapter

13.2Two front doors: the portal and the endpoint

Stardog Cloud has two things with two addresses. The portal, cloud.stardog.com, is where you sign in with your email: a control panel that lists your endpoints, launches the web apps, and manages API keys. The endpoint, https://<your-endpoint>.stardog.cloud:5820, is the actual Stardog 12.1.4 server in us-west-2. It has its own HTTP API (POST /kit-c360/query runs SPARQL) and its own users, unrelated to portal accounts.

That's the answer to the puzzle. In Studio, the portal connects to the endpoint on your behalf. A Python script has no portal in the middle, so it must bring credentials the endpoint knows, which your email isn't. Hence this project's native Stardog user, stardog_admin, with the role cloud, plus hr since Chapter 12: with named-graph security on, cloud alone reads no graphs, and hr grants each graph by name. Every program in this book, including the Chapter 14 agent, signs in as stardog_admin (or as one of the narrower users from Chapter 12).

13.3Studio, Designer and Explorer: one graph, three audiences

Studio is the engineer's IDE, the tool you've lived in since Chapter 2. What DBeaver is for SQL, Studio's Workspace is for SPARQL. It holds the query editor with its reasoning toggle (Chapter 10), Databases for loading data and setting properties (Chapter 6), the Models view, the Data area for data sources and virtual graphs (Chapters 7 to 9), and Security (Chapter 12).

Designer is for modelers. You draw classes as boxes and relationships as arrows, attach a table or CSV to each class, and publish; Designer writes the ontology into a named graph and creates the mappings. Its fingerprints are in the kit: in c360_extended_rules.ttl, each rule:content has a <tag:stardog:designer:rule:content> copy and a compressed designer:rule:data blob from Designer's rule editor. So why write everything by hand? Because when something breaks (a missing sql.schemas, the reserved word date, a float drifting by two cents), you need to know what Designer generates underneath: the same triples, just faster.

Explorer is for browsing: search for a customer, land on her page, click her address or an order, and keep walking. It's Chapter 2's "follow the arrows" as a web page; the kit's kit.yaml gives it a starting point, initialSearch: "`urn:stardog:demos:c360:customer:230`". Its search depends on the full-text index (search.enabled), and virtual-graph data isn't stored in Stardog, so it may not be indexed. If Explorer can't find "Carolyn Inworth" but your Chapter 9 query can, that's probably why; check the docs for your version before promising Explorer on a purely virtual setup.

13.4Voicebox: English in, SPARQL out

A business user types "Who are the top spenders in Wisconsin?" and Voicebox writes SPARQL, runs it, answers in a sentence, and shows the query. Underneath is a large language model (LLM), but what makes it work is your semantic layer. Press Play to watch.

How does Voicebox know how to query this ontology?

Not from its training data. It reads four things you built:

1. The ontology (the T-Box). Per the Voicebox developer guide, it uses rdfs:label for names, rdfs:comment for descriptions, rdfs:subClassOf for the hierarchy, and so:domainIncludes/so:rangeIncludes for which properties connect which classes. The guide recommends the schema.org pair over rdfs:domain/rdfs:range, the practical reason the c360 kit uses them (Chapter 6). "Spenders" matches no class, but it lands near the labels "price", "quantity" and "purchased by".
2. The search index. "Wisconsin" is a value, not part of the ontology. Voicebox finds values with full-text search, which is why enabling Voicebox also switches on search.enabled.
3. Example questions. Shared stored queries tagged with system:voiceboxQuestion are shown to the LLM as worked examples. This is few-shot prompting: teaching by showing a few solved problems.
4. The engine. Stardog runs the finished query the normal way, virtual graphs and pushdown included (Chapter 9).

Here is one of the kit's 317 stored queries, trimmed; each pairs English with SPARQL:

system:QueryQ10546 a system:StoredQuery , system:SharedQuery ;
  system:queryDatabase "kit-c360" ;
  system:voiceboxQuestion "Which rewards account customers bought at least $10K in a single order?" ;
  system:queryString """SELECT DISTINCT ?customer0 WHERE {
  ?order0 a ecomm:Order .
  ?order0 ecomm:purchasePrice ?dat_0 .
  ?order0 ecomm:purchasedBy ?customer0 .
  ?customer0 ecomm:hasRewards ?rewardsAccount0 .
  FILTER ("10000.00"^^xsd:decimal <= ?dat_0)
}""".

This one example teaches that the arrow runs from order to customer (?order0 ecomm:purchasedBy ?customer0), that money is compared as xsd:decimal, and that the query returns IRIs rather than names. The docs recommend exactly that (Voicebox looks up the labels before showing results), and suggest starting with five to ten examples that together cover the whole model.

Three notes for our database. First, Voicebox has to be on: the database option voicebox.enabled (the kit's kit.yaml sets it to true) can only be enabled if the server's license allows Voicebox. Second, a Voicebox app lets you choose its data graph, schema and reasoning setting. Our facts live only in virtual graphs, so if Voicebox finds nothing where your Chapter 9 query finds Carolyn, check that setting first. Third, the kit's examples were written for its CSV data, and a couple use properties our mappings don't produce (ecomm:race). The best examples are ones you write, such as your Chapter 9 query saved as "Who are the top spenders?".

13.5Stored queries and knowledge kits

A stored query is SPARQL saved on the server under a name, with metadata. The kit ships its 317 as Turtle, since Stardog keeps stored queries as triples in its system catalog. The types: system:StoredQuery (saved), system:SharedQuery (visible to others; Voicebox learns only from shared ones), and system:ReasoningQuery (run with reasoning on). In Studio you save one from the editor. Chapter 14's five competency questions, with their verified queries, are ideal candidates: a regression suite, Voicebox examples, and reference answers for the agent.

A knowledge kit is a semantic layer in a box. Its manifest, kit.yaml, reads like this book's summary:

The fourth row is the interesting one. The kit materializes its data (Chapter 7's ETL-style option). You kept its model, rules and IRI patterns and swapped that one section for live virtual graphs. Because your mappings mint the same IRIs (urn:stardog:demos:c360:customer:{cid} and friends), the kit's rules and stored queries still fit: the Chapter 9 IRI trick pays off a second time.

13.6The Stardog Cloud MCP server

MCP (Model Context Protocol) is an open standard for connecting AI applications to tools. An MCP server advertises tools, each with a name, a description and a JSON schema for its arguments. An MCP host (Claude Desktop, Claude Code, Cursor, or your own agent) discovers them and lets its model call them. MCP is to AI tools roughly what JDBC is to databases: one standard plug.

Stardog publishes an open-source server on GitHub, stardog-union/stardog-cloud-mcp. Its README lists exactly three tools, all built on the Voicebox APIs:

To run it you need a Voicebox API token: in the portal's profile menu, choose Manage API Keys, create an application and generate a secret. That's a third kind of credential, neither your portal login nor stardog_admin. Not on the Free tier. The Voicebox developer guide says "Manage API Keys" only appears "if your organization has been given Voicebox API access", and on a Free account the profile menu has no such entry (checked: it lists Update Profile, Update Cookie Consent, Logout, My Workspace and Delete Account; a Stardog Community thread reports the same). No key means no MCP server, so on the Free tier read this part along. Nothing later depends on it: the Chapter 14 agent talks to Stardog directly with a username and password (stardog_admin, hr_user or marketing_user). Locally, the server runs on Python 3.12 or 3.13 with uv, started by the host (uv run stardog-cloud-mcp --token … --client_id …). The remote mode is beta: a Docker container serving HTTP on port 7001, with the token in an x-sdc-api-key header.

13.7Which tool, for whom, with which login