Commands
SAL commands operate on a Git-backed project and the generated data under .sal/data.
For a step-by-step flow, start with Getting Started. For more info on internals, the AI-generated DeepWiki may be helpful.

sal init
Section titled “sal init”Initializes a SAL project in the current Git repository. The repository must not be your home directory and must already have a Git remote.
sal init asks one question, a sentence or two describing the project, and records the answer in .sal/config.jsonld on the project’s own node, which sal serve --with-ui shows under the data product’s name. The description is required; pass --description to give it without being asked. A directory that already has a .sal/config.jsonld is already a SAL project, and sal init fails rather than write over what it records.
Description of the project: A demo project for sal; a small dataset of stream gauges and the agency that runs them{ "@id": ".", "@type": "schema:Project", "dcterms:title": "sal-demo", "dcterms:description": "A demo project for sal; a small dataset of stream gauges and the agency that runs them"}The node is the project itself, resolved against the base IRI the git remote gives, and dcterms:title is the last segment of that remote, the repository name; sal import types the same node owl:Ontology and records the imports on it, and sal build validates and commits its statements like any other source, so the description is a triple of the data product too.
sal init creates:
.sal/datain the project for generated data..sal/config.jsonldholding the project node above;sal importandsal buildadd to the same file. See the project config file.sparql/in the project root for the project’s SPARQL queries, which is wheresal buildandsal constructlook forCONSTRUCTqueries. An existing directory is left as it is.~/.sal/cachefor user-level cache data.~/.sal/config.jsonldfor user-level SAL configuration..gitignoreentries for.sal/dataand.sal/constructed.- A
Makefiledocumenting the commands a project runs:make validate,make build MESSAGE="...",make query,make serve, and so on, each onesalcommand, plusmake apply,make destroy, andmake uploadfor the deploymentsal terraformwrites. It is documentation that happens to run rather than a build system, and an existingMakefileis left alone.

Agent skills
Section titled “Agent skills”sal init also installs the agent skill that teaches Claude Code, Codex, and other coding agents how to work with the repository: the sal skill for a project, the salmodule skill for a module. The skill is downloaded from the sal repository with git and copied into both .claude/skills/<name> (where Claude Code reads it) and .agents/skills/<name> (where agents following the Agent Skills convention read it); the copies are identical, and both belong in git so the whole team’s agents see them. --no-skills skips it. A download that fails, offline say, is a warning rather than a failed init; sal init --skills in an initialized project installs the skill and nothing else, which is also how to update it.
Common vocabularies
Section titled “Common vocabularies”A new project also gets the common vocabularies downloaded into .sal/data/blobs, so a build that uses one needs no network and a vocabulary publisher that is slow or unreachable from where the build runs cannot fail it: RDF, RDFS, OWL, Dublin Core terms and elements, schema.org, SOSA, SSN, QUDT, SKOS, FOAF, PROV-O, DCAT, GeoSPARQL, OWL-Time, and SHACL. They are seeded, not pinned: .sal/data/blobs/seed.jsonld indexes the documents by digest, and .sal/config.jsonld lists a vocabulary only once a build uses it, at which point the build pins the seeded document instead of fetching it (--no-cache ignores the seeds and fetches from the publisher). A document that cannot be downloaded or is not RDF is skipped with a warning and fetched by a build if it is ever used. --no-vocabularies skips the download. A fetch a build does make is retried up to four times with backoff on a network error, timeout, or 5xx answer, and an unreachable host is reported with how to seed the vocabulary instead.
sal init --with-iac
Section titled “sal init --with-iac”--with-iac also writes the Terraform configuration sal terraform generates into terraform/, so a project starts with the deployment the Makefile’s make apply runs. A terraform/ that already holds a configuration is left alone.
sal init --salmodule
Section titled “sal init --salmodule”Initializes the repository as a SAL module rather than a SAL project: a module is a container that produces data for projects, so none of the project layout (.sal/data, .sal/config.jsonld, sparql/, the .gitignore entries) is created and no description is asked for. It checks the git remote the way sal init does, since the remote names the module, and then opens a form in your browser that writes ontology.jsonld. Where no browser is likely to open, in CI, over SSH, without a terminal, or on Linux without a display, it says so and asks its questions at the prompt instead; --no-ui asks at the prompt anyway and --ui opens the form anyway. Either way it scaffolds the files a module needs in the repository root:
ontology.jsonld, a skeleton of the document the module’ssalmodule ontologycommand prints: a@contextbinding the prefixes it uses and a@graphholding anowl:Ontologynode followed by oneowl:Classthat is a subclass ofsalmodule:Task. The ontology node is"@id": ".", itsdcterms:titleis the git repository name, itsdcterms:creatoris the configured gituser.name, and itsowl:versionInfostarts at0.1; every other string starts blank for you to fill in.- A
Dockerfileholding only a comment reminding you that the image must stream JSON-LD to standard out per the salmodule specification. - A
.dockerignoreholding only a comment saying it excludes files from the module container. .vscode/salmodule-ontology.schema.json, the JSON Schema for a SAL module ontology, and ajson.schemasentry in.vscode/settings.jsonapplying it toontology.jsonld, so that VS Code and any other editor reading that setting flags a missing ontology node, a task class that is not a subclass of asalmodule:task class, ash:nodeKindthat is not one of SHACL’s, or a constraintsalrefuses in asalmodule:stdoutShapeorsalmodule:stderrShapewhile you type. An existingsettings.jsonkeeps everything it has and gains only the entry; one thatsalcannot parse as JSON, because it holds comments for instance, is left alone with a warning showing the entry to add by hand.sal validatechecksontology.jsonldagainst the same schema, so what the editor flags and whatsalrefuses are one set of rules.
A file that already exists is left unchanged, so the flag is safe to re-run. The schema copy is the one exception, since it is sal’s rather than the module’s: a newer sal rewrites it.
So that the ontology starts with a worked example rather than blank fields, the prompt asks three questions about one task the module will offer: a unique ID with no spaces or special characters (it becomes the class’s @id and the @type a project instance uses), a human readable name (rdfs:label), and a comment about what the task does (rdfs:comment). An ID with a space or punctuation is asked for again. The task class’s salmodule:taskShape then becomes a sh:NodeShape targeting that class with an empty sh:property list, ready for the constraints on the task’s configuration properties:
Unique ID for the task, with no spaces or special characters (e.g. FetchStations): FetchStationsHuman readable name for the task (e.g. Fetch weather stations): Fetch weather stationsComment describing what the task does: Fetches every station in a region and emits it as schema:Place{ "@context": { "dcterms": "http://purl.org/dc/terms/", "owl": "http://www.w3.org/2002/07/owl#", "rdfs": "http://www.w3.org/2000/01/rdf-schema#", "salmodule": "https://w3id.org/sal/salmodule#", "sh": "http://www.w3.org/ns/shacl#" }, "@graph": [ { "@id": ".", "@type": "owl:Ontology", "dcterms:creator": "Ada Lovelace", "dcterms:title": "my-module", "owl:versionInfo": "0.1", "rdfs:label": "", "rdfs:comment": "" }, { "@id": "FetchStations", "@type": "owl:Class", "rdfs:subClassOf": { "@id": "salmodule:Task" }, "rdfs:label": "Fetch weather stations", "rdfs:comment": "Fetches every station in a region and emits it as schema:Place", "salmodule:taskShape": { "@type": "sh:NodeShape", "sh:targetClass": { "@id": "FetchStations" }, "sh:property": [] } } ]}Pass --bare to open no form and ask no questions. The task class is then written with every string blank and "salmodule:taskShape": {}, which is also what you get at the prompt when standard input is not a terminal. The schema flags each of those blanks in the editor until it is filled in.
sal init --salmodule --baresal init --salmodule in the browser
Section titled “sal init --salmodule in the browser”By default sal init --salmodule writes ontology.jsonld from a form in your browser rather than from the questions at the prompt. sal serves the form on a localhost port it prints, opens it in your browser, and keeps running until you press Ctrl+C. It falls back to the prompt where no browser is likely to open (CI set, an SSH session, standard output that is not a terminal, or no DISPLAY on Linux), saying why; pass --ui to open the form regardless, say over SSH with a forwarded port, or --no-ui to answer at the prompt on a machine with a browser.
sal init --salmodule # the form, or the prompt where no browser would opensal init --salmodule --no-ui # the promptsal init --salmodule --ui # the form, wherever it runsThe form is a page of the same web UI sal serve --with-ui serves, in the same light and dark themes, and has a ? beside each part saying what it is for. It asks for:
- the module:
dcterms:titleanddcterms:creator, filled in from the git repository name anduser.name,owl:versionInfo, which starts at0.1, and anrdfs:commentdescribing the module; the title, version, and description are required before the document can be written; - the prefixes: the six every module ontology binds (
salmodule,owl,rdfs,dcterms,sh, andxsd) are always there, and you add the ones your shapes refer to,schemaforhttps://schema.org/say; - the tasks: each one an
owl:Classsubclassingsalmodule:Task, with its ID,rdfs:label, andrdfs:comment, and an editor for each of its SHACL shapes,salmodule:taskShape,salmodule:stdoutShape, andsalmodule:stdinShape, written as JSON-LD using the prefixes above. The task shape starts as the node shape targeting the task that the prompts write, and each editor has a button that inserts a worked example to edit from; an editor left empty declares no shape.
The pane beside the form shows the ontology.jsonld that would be written, and it is checked as you type with the same rules sal validate --salmodule applies: the JSON Schema, that every term of the module’s own namespace is declared, that every shape is one sal can enforce, and that a shape’s JSON parses at all. Each problem is listed and marked on the line it is about, and the Write button is enabled only once there are none. Writing creates ontology.jsonld with exactly the text shown, along with the Dockerfile, .dockerignore, and editor schema sal init --salmodule scaffolds, leaving any that already exist alone.
The same form edits an ontology that exists: run in a module that already has an ontology.jsonld, it loads the file into the form, and Save writes the file back, which is what sal edit opens. Below the preview, once the document is written, is a prompt for a coding agent; see sal edit.
sal edit
Section titled “sal edit”Opens the browser form sal init --salmodule creates ontology.jsonld with, loaded with the module’s ontology.jsonld, so a module’s ontology can be changed without knowing how the document is put together. Run it in the module’s root:
sal editThe form shows the module (title, creator, version, and description), the prefixes the shapes use, and each task with its label and comment and three shapes, which the form shows as rows rather than SHACL:
- Configuration (
salmodule:taskShape): one row per property a project configures an instance with. The row’s name becomes a term of the module, declared with its type and range where it is constrained, and its value kind (text, integer, decimal, true or false, date, date and time, URL, IRI, or anything), required, and single boxes become the datatype and cardinality constraintssalvalidates an instance against before running the task. - Output (
salmodule:stdoutShape): the class the task’s nodes carry as@typeand one row per property every node must have, whichsalchecks each line of the task’s output against. - Input (
salmodule:stdinShape): the same for the nodes a consuming task reads.
A shape holding a constraint the rows cannot show (sh:pattern, sh:in, a nested shape) is edited as JSON instead, every shape has an Edit as JSON button for the rest of SHACL, and an undeclared shape can be declared straight as JSON to paste a shape into; Edit as form turns JSON back into rows when it holds only what the rows can show. The examples the editor inserts use Dublin Core Terms, which every module ontology binds. Nothing the file holds is lost by editing it in the form: a context entry that is not a prefix, a key on a node the form has no field for, and any node that is neither the ontology node nor a task class are written back as they were, and the preview shows exactly what will be written. The document is checked as it is edited with the rules sal validate --salmodule applies, and Save is enabled once there is no problem and the text differs from the file. A file edited by hand while the page is open is not written over; the page says to reload.
While the button is greyed out, a folded list under it says what to fix or fill in: the problems the form found, the ones sal found with their lines, or that the file already holds the document.
sal edit --prompt prints a prompt for a coding agent, written by sal from the ontology: the module’s namespace and prefixes, every task with its configuration properties, output shape, and a sample of the task instance the container is handed, the contract the run command keeps (newline delimited JSON, error nodes, file:/// hand-over), and the commands that check the result. Paste it into Claude Code, Codex, or any other agent, which then writes the Dockerfile and the code from it; sal edit --agents writes it as AGENTS.md in the module root instead, headed by a marker that lets sal write it again, and never touches one written by hand. The prompt tells the agent to read the installed salmodule skill first when .claude/skills/salmodule or .agents/skills/salmodule exists, and how to install it otherwise. Neither opens the form.
sal edit --prompt | pbcopysal edit --agentsThe form is served on a localhost port sal prints and keeps running until Ctrl+C; --port fixes the port, for forwarding it over SSH, and --ui opens the browser even where sal would not on its own.
sal import
Section titled “sal import”Records an external ontology in the project so that every build carries it.
sal import https://www.w3.org/ns/sosa/The import is written to the ontology node of .sal/config.jsonld, which sal import creates the first time it runs. .sal/config.jsonld also carries sal build’s pinned vocabulary versions as the rest of its @graph; see Data Layout for the full shape.
{ "@context": { "dcterms": "http://purl.org/dc/terms/", "owl": "http://www.w3.org/2002/07/owl#", "rdfs": "http://www.w3.org/2000/01/rdf-schema#", "schema": "https://schema.org/" }, "@graph": [ { "@id": ".", "@type": ["schema:Project", "owl:Ontology"], "dcterms:title": "my-project", "dcterms:description": "A demo project for sal; a small dataset of stream gauges and the agency that runs them", "owl:imports": [{ "@id": "https://www.w3.org/ns/sosa/" }], "rdfs:comment": "Represents the ontology for the my-project project overall and all the vocabularies that are directly materialized into the graph, not just referenced." } ]}"@id": "." is the project itself, which is the same base sal build resolves the project’s own relative terms against.
dcterms:title is the Git project name sal init recorded; pass --title to replace it, on the first import or on any later one.
rdfs:comment is always generated.
Several ontologies can be imported at once, and importing one that is already listed leaves the file unchanged:
sal import https://www.w3.org/ns/sosa/ http://www.w3.org/ns/ssn/.sal/config.jsonld is a normal source file that belongs in Git; only .sal/data is ignored.
sal build validates the ontology node and counts it alongside the project’s other RDF, so the statements it makes about the project land in the data product.
The ontology node is regenerated on every import.
A statement added by hand survives, since sal import keeps anything the generated shape does not cover; JSON has no comment syntax, so unlike the Turtle this file used to be written as, there is no autogenerated banner to preserve either.
Any pinned vocabulary nodes already in .sal/config.jsonld are carried forward untouched, since sal import never inspects them.
Importing a SAL module’s ontology
Section titled “Importing a SAL module’s ontology”A salmodule:// reference imports the vocabulary a SAL module publishes:
sal import salmodule://github.com/adplincinst/sample-salmodule-1The module is recorded like any other import:
{ "@id": ".", "@type": ["schema:Project", "owl:Ontology"], "dcterms:title": "my-project", "owl:imports": [{ "@id": "salmodule://github.com/adplincinst/sample-salmodule-1" }]}A module ontology is not served over HTTP, so sal build resolves the import the way the SAL Module specification
says a salmodule:// IRI is dereferenced: it clones the repository, builds the Dockerfile in its root, and runs
the image’s salmodule ontology command. The JSON-LD the module prints is merged into the data product, so the
module’s terms end up in the triples table alongside the project’s own.
The host may be left out, in which case github.com is assumed; salmodule://adplincinst/sample-salmodule-1 and
salmodule://github.com/adplincinst/sample-salmodule-1 are the same import.
Importing a module records it but does not build it, exactly as importing a URL records it without fetching it.
Nothing is cloned or built until sal build runs.
Importing another data product
Section titled “Importing another data product”An oci:// reference imports a published SAL data product rather than an ontology document:
sal import oci://ghcr.io/cgs-earth/water:v1Unlike the other kinds, an artifact is pulled as it is recorded, into .sal/data/imports/ under a directory named
after the artifact itself. That path sits inside .sal/data, so what was pulled is not committed to Git;
re-running sal import on an artifact already listed restores it to disk rather than skipping it.
Pass --username and --password for a private registry, or set OCI_USERNAME and OCI_PASSWORD.
sal build reads only the environment variables, since it takes no registry flags of its own.
Because artifacts are laid out by name, a project holds one version of each at a time.
Importing oci://ghcr.io/cgs-earth/water:v2 replaces the :v1 entry in .sal/config.jsonld’s ontology node and deletes what it
pulled.
An imported data product’s triples are not merged into your table.
Its Iceberg table is registered beside your own instead, so sal query gets a view named after the artifact
(water) next to triples, plus an imports view stacking every imported product with a view column naming
which one each row came from.
An import that has not been pulled, or that holds no Iceberg table, is skipped rather than failing the query.
A reference such as ghcr.io/my-org/my-ontology:latest, written without a scheme, is recognized as an artifact
and reported as a missing oci:// rather than treated as a malformed URL.
sal validate
Section titled “sal validate”Validates RDF source files without committing a new data product. Use it while editing Turtle or JSON-LD files:
sal validate data/Important flags:
--prefix-maps: apply prefix mappings assource=targetentries or source/target pairs.--format: chooseicebergornq; defaults toiceberg.--no-cache: resolve every vocabulary from its source instead of from the versions pinned in.sal/config.jsonld.--allow-prefixes-without-slash-or-hash: include a prefix whose namespace does not end in/or#without asking.--salmodule: also check the project as a SAL module; implied whenontology.jsonldand aDockerfileare both in the project root. Seesal validate --salmodule.
sal validate reads the project’s pinned vocabulary versions but never writes them; only sal build records a pin.
Run outside a SAL project, it resolves vocabularies from their sources with nothing pinned at all.
Since it writes nothing, it does not require a clean Git working tree the way sal build does; it validates the files as they are on disk, committed or not.
An undefined term is reported with the file and the line number it appears on:

The prefixes the source files declare are checked as well as the terms used from them:
- A namespace that ends in neither
/nor#, such as<https://foo.com>, is almost always a mistake, since a term is joined straight onto it (https://foo.comnamerather thanhttps://foo.com/name). It is not invalid RDF, so validation warns, names the files that declare it, and asks whether to include it. Answeryto include it as written, or pass--allow-prefixes-without-slash-or-hashto include every such prefix without being asked; anything else fails the run. - The same vocabulary declared under two spellings that differ only by
http/httpsor by a trailing/or#, such as<http://schema.org/>in one file and<https://schema.org/>in another, is an error. Terms written against the two never compare equal, so the vocabulary would end up in the data product under two IRIs. Declare the same namespace everywhere, or fold the spellings together with--prefix-maps. http://schema.org/is an error. schema.org defines every term underhttps://schema.org/, so a term written against thehttpnamespace names nothing the vocabulary defines. Declare<https://schema.org/>, or map thehttpspelling onto it with--prefix-maps http://schema.org/=https://schema.org/for a file you cannot edit.
schema.org is also resolved differently from other vocabularies: its namespace answers with an HTML page whatever format is asked for, so the vocabulary is fetched from the release document at https://schema.org/version/latest/schemaorg-current-https.jsonld and pinned against https://schema.org/ like any other namespace.
Validating a file that references a SAL module clones and builds that module so its vocabulary can be checked.
sal validate does not run module tasks; only sal build does.
sal validate --salmodule
Section titled “sal validate --salmodule”A SAL module repository is a SAL project too, and sal validate checks it as one: ontology.jsonld is RDF like any other source file, so an undefined sh: or owl: term in it is reported the same way as in any other file.
With --salmodule, or whenever the project root holds both an ontology.jsonld and a Dockerfile, it also checks the module itself, without building the image or running anything:
- Both files exist. With
--salmodulea missing one is an error; without the flag the module checks only run when both are there. ontology.jsonldhas the structure the specification requires, checked against the same JSON Schema thatsal init --salmoduleinstalls for the editor: a@contextbindingsalmoduleandowl, exactly oneowl:Ontologynode named"@id": ".", at least oneowl:Classthat is anrdfs:subClassOfofsalmodule:Task, IRI references written as{"@id": ...}, SHACL constraint values of the right kind, and no constraintsalrefuses in asalmodule:stdoutShapeorsalmodule:stderrShape.- Every term of the module’s own namespace that the document uses is declared: a relative
@idthat a shape, anrdfs:domain, anrdfs:range, or a@typerefers to has a node in@graphwith that@idand an@type. A key that is neither prefixed nor defined in@contextis reported too, since a JSON-LD processor drops such a key without a word. - Every SHACL shape is a well-formed shape for the implementation that enforces
salmodule:stdoutShapeandsalmodule:stderrShapewhen a task runs, and nostdoutShapeorstderrShape, including one it refers to by@id, uses a constraintsalrefuses.
Each problem is reported with the file and the line it is on, the way an undefined term is:
ontology.jsonld:13: rdfs:subClassOf is an IRI reference, written {"@id": "salmodule:Task"}; a bare string is a literal that sal ignoresontology.jsonld:18: undefined term regionn: no node in @graph declares "@id": "regionn" with an @typeThe module’s relative terms resolve against the salmodule:// namespace derived from the repository’s git remote, salmodule://github.com/OWNER/REPO/ for a repository on GitHub; a repository with no remote is checked under a placeholder namespace, which changes nothing about what is reported.
Run with a single directory argument, sal validate path/to/module, the directory named is the one checked.
sal build
Section titled “sal build”Validates RDF source files and writes the merged graph into the local data product.
sal build --message "Add the 2024 stream gauges" data/Every build records a message saying what it changes, the way every Git commit carries one.
--message (-m for short) gives it; without one, the build records the message of the Git commit the worktree is checked out at, since a build of a clean worktree is a build of that commit.
A build of a worktree with uncommitted changes, which only --force allows, matches no commit, and a repository with no commit yet has no message to take, so both are refused without a --message, with an error that says so and points at sal validate, which checks the project without committing anything.
The message is recorded in the summary of the Iceberg snapshot the build commits, under sal.message, next to the triples the snapshot added and removed under sal.triples.added and sal.triples.removed, so it is read back wherever the snapshots are listed: sal query --info snapshots, the Snapshots table of the UI’s Stats tab, and the description of the artifact sal push publishes, which carries the latest one.
A build that finds no new triples commits no snapshot and so records no message; it warns that it dropped it.
By default, sal build requires a clean Git working tree.
Use --force only for test or debugging builds.
Important flags:
--message,-m: what this build changes; defaults to the message of the Git commit the worktree is at, and is required with uncommitted changes.--prefix-maps: apply prefix mappings before validation.--format: chooseicebergornq; defaults toiceberg.--force: build even when the Git working tree has uncommitted changes.--no-cache: resolve every vocabulary from its source again and re-pin it in.sal/config.jsonld.--allow-prefixes-without-slash-or-hash: include a prefix whose namespace does not end in/or#without asking, as forsal validate.--without-sal-modules: commit the configuration of every SAL module task the sources declare without running any of them; see SAL module tasks below.--no-tui: write the log to stderr as it happens instead of opening the progress and log panes.
sal build pins the exact version of every vocabulary the project resolves against, so a later build validates against the same versions this one did.
That includes the vocabularies the output of a SAL module task is stated in: a namespace the module ontology’s @context, or a @context a node of the output carries, binds a prefix to is pinned once the task has run when the output used a term of it as a predicate, as the class it types a node with, or as a literal’s datatype, since those terms reach the table like the sources’ do, so a module that emits schema.org data under a schema prefix lists https://schema.org/ among the project’s vocabularies even though no source file declares it. Only what the output uses through a binding counts: not a prefix the module’s own ontology binds for its shapes without the output using it, and not a term the output writes as a full IRI, which refers to something the way a full IRI in a Turtle file does rather than declaring a vocabulary, so a harvested node typed with a class of an ontology the module never bound does not pin that ontology. Unlike a declared prefix, one of these that cannot be resolved only warns, since module output is never validated against its vocabularies.
A build that pinned something new writes .sal/config.jsonld, which belongs in Git; commit it before the next build, which otherwise refuses to run against a dirty working tree.
Every pinned version is also written into the data product itself as owl:Ontology provenance, so it is queryable alongside the data rather than only recorded in the lockfile.
See Pinned vocabularies for the file’s shape, where the documents it names are stored, and a sample query.
Only triples that are not already in the table are committed, so rebuilding unchanged sources creates no new snapshot:

sal build validates the project ontology node in .sal/config.jsonld alongside the project’s other RDF if the project has one,
then dereferences every ontology it lists with owl:imports and merges those statements into the data product.
A salmodule:// import is dereferenced by cloning and building the module and asking it for its ontology.
An import that cannot be fetched fails the build, naming the ontology that could not be resolved.
sal validate does not fetch imports; only sal build does.
Importing an ontology is also what makes its class and property hierarchies walkable by a SPARQL property path, since a query reads only what the table holds; see Reasoning over the graph. A vocabulary the project only validates against is pinned and recorded as provenance, but none of its own statements reach the table.
The last thing a build does is describe the table it just committed as a STAC catalog under .sal/data/stac.
The catalog lists one collection, the triples table, carrying the STAC Iceberg extension: the table’s current metadata.json location and snapshot ID, its Iceberg format version and partition spec, its columns, its row count, and the bounding box of every geometry it holds, all read from the table after it is written. It also links, as further children, every STAC catalog a SAL module task handed over as a directory under .sal/data/blobs, so the data product and what its modules produced are one catalog tree.
sal serve exposes it at /stac/catalog.json; see STAC catalog for what the documents contain.
SAL module tasks
Section titled “SAL module tasks”A build is the one operation that produces a snapshot of the data product, so it also runs every SAL module task the source files declare and commits what the modules produced in the same snapshot as the sources.
For each module’s referenced task instance(s), sal build clones the module’s repository, builds the Dockerfile in its repository root,
and invokes the module’s run command with the task instance serialized from the instance’s RDF properties.
The clone never prompts for credentials: a private repository is cloned only when a git credential helper already holds a token for it
(gh auth setup-git configures one), and otherwise the build fails saying so rather than waiting on a prompt.
The newline delimited JSON the module writes to stdout is converted to triples and committed alongside the
sources. A relative IRI in that output resolves against the project’s namespace, not the module’s, so a task’s
output is named as the project’s own data unless the module wrote absolute IRIs.
The output is converted as the task writes it, in batches of lines, and written straight to Parquet files in
.sal/data/.scratch rather than held in memory, so a task may produce far more triples than the machine has
memory for. The build then compares those files, and everything else it gathered, with the table in an embedded
DuckDB database that spills to the same directory once its memory is used, writes the
triples the table lacks, and deletes the ones it no longer holds. What a build needs in memory is therefore bounded
by the project’s own sources and not by what its modules produce; what grows with the data is disk, roughly the
size of the module output as Parquet, which is removed again once the build is done. A blank node a module writes
is local to the line, the node, it is written on: it is named from that node alone, so the same output gives the
same names whatever surrounds it, and two nodes alike in every statement, IRIs included, are stored once.
sal build works out how much memory it may use on its own: the memory limit of the container it runs in (its
cgroup), else the machine’s physical memory. It holds the Go heap to 70% of that and the DuckDB database to 50%,
since the two are rarely busy at once, and logs the figures when it starts. A GOMEMLIMIT you set wins over the Go
share, and SAL_MEMORY_LIMIT, a size such as 8GiB, replaces the budget itself where sal detects the wrong one.
In a JSON-LD-heavy project the progress pane shows, once a task passes 20,000 nodes, how many JSON-LD documents it
has read so far, and the log says so every 20,000.
A file:/// IRI in that output names a file inside the container; sal build copies it into .sal/data/blobs
under its SHA-256 digest while the task runs, rewrites the reference to urn:sha256:{digest}, and describes the
copy with the file:/// IRI the task wrote as rdfs:label, its modification time as dcterms:modified, its digest as owl:versionIRI,
its path under .sal/data/blobs as dcterms:identifier, and the module that produced it as dcterms:source. A file:/// IRI ending in a slash names a directory,
copied whole under .sal/data/blobs/{digest}/ with its files verbatim, so that it can be read in place, labelled with the same file:/// IRI.
Every copy is appended to .sal/data/blobs/prov.jsonld under its urn:sha256: IRI, and every later sal build carries those records into the table as provenance, so a table
built again from source still describes every copy. prov.jsonld is a log: a build only ever adds to it and to .sal/data/blobs, and never removes what an earlier
build copied, so clearing old copies is up to the user, with sal clean --wipe or by hand. See Using SAL Modules, including
Files a task produces.
sal build --without-sal-modules skips running the tasks. The build still validates each task’s configuration against the module’s own ontology, the same way any other term
is checked against its vocabulary, and commits that configuration RDF into the data product like any other statement; only the modules’ run commands are never invoked.
Use it when the sources should be committed without waiting on a module, or on a machine without a docker daemon to run one on.
A project that declares no module tasks builds the same with or without the flag.
Constructed triples
Section titled “Constructed triples”Once the sources are validated, the imports merged, and the module tasks run, a build runs every SPARQL CONSTRUCT query in the project’s sparql/ directory over all of it and adds the triples they construct to the graph before anything is committed.
The sources, the module output, and the constructed triples are therefore one Iceberg snapshot: they are committed together and roll back together.
PREFIX schema: <https://schema.org/>
CONSTRUCT { ?b schema:knows ?a }WHERE { ?a schema:knows ?b }- A file is a query when it ends in
.rqor.sparql, insparql/or a directory under it. A file holding aSELECTis left alone. - A query that does not parse, or that uses syntax the SPARQL engine does not translate, fails the build before anything is fetched or run, naming the file.
- Every query reads the build as it stood before any query ran, so a query never sees what another constructed and the order they run in does not matter.
- The queries are answered by the same SPARQL to SQL translation
sal serveuses, which reads a table. The build is staged on a branch of the project’s own table,sal-staging, for them to read. Only the triples the table does not hold yet are written, and the build commits those same files with the constructed triples as one snapshot, so nothing is copied. The branch and its snapshot are removed before the build finishes, whether or not it succeeded. - Constructed triples are not checked against the project’s vocabularies, the same as module output.
- The queries are hashed with the source files, so changing one changes the
sal.hashthe table records.
The build also writes what each query constructed to .sal/constructed, exactly as sal construct does.
See Data Layout for the generated table structure.
The validation, every module built or run, and the Iceberg diff and write are recorded as OpenTelemetry spans when an exporter is configured; see Telemetry.
Progress and log panes
Section titled “Progress and log panes”In a terminal, sal build and sal run work under two panes, one on screen at a time, and so do sal push, sal pull, and sal clone, with the phases of a transfer in place of a build’s:
- Progress lists the phases of the build in the order they happen, validating the sources, importing ontologies, running SAL module tasks, running
CONSTRUCTqueries, and writing the Iceberg table, each marked upcoming, running, done, failed, or skipped, with how long it has taken so far. Under a running phase are the steps inside it as they happen, each with its own time: every document validated and vocabulary loaded, every module cloned, built, or reused from a cached image, every task run with how much it has written and how many files it has copied, every query, and the diff, Parquet write, and commit of the table. A phase says how far it is, such as3/7 documentsor1/2 tasks · 2 modules, and completed steps fold into one line counting them once more than a few have passed, so the pane stays a screen tall over hundreds of files. A failed step shows the first lines of its error where it failed. - Logs is the log exactly as
sal buildwrites it without the panes, wrapped to the terminal, following new lines as they arrive until you scroll up.
Tab, 1, or 2 switch panes, the arrow and page keys or the mouse wheel scroll the one on screen, End resumes following the log, and Ctrl+C cancels the build.
A yes/no question the build asks, such as whether to include a prefix whose namespace ends in neither / nor #, appears above the help line and is answered with y or n.
The panes close as soon as the build finishes, and a summary is printed in their place so the terminal keeps a record: how the build ended and after how long, the phases and steps with their times, and the path of the log file, which holds every line the Logs pane showed and is written under /tmp/sal/logs whether or not the panes were shown.
An error that fails the build is still printed after the summary.
The panes need stdin and stderr to be a terminal and open only outside CI; a build run from a script, with its output redirected, or on a CI runner (recognized by the CI variable every major provider sets, or the provider’s own such as GITHUB_ACTIONS or GITLAB_CI, even when the runner attaches a pseudo-terminal) logs to stderr as it always has, and --no-tui asks for that in a terminal too.
The progress pane reads the same spans Telemetry describes, so what it shows is what a trace of the build records.
sal run
Section titled “sal run”Re-runs every SAL module task the project’s RDF declares on top of the last build and commits the triples the modules produced as a new snapshot of the data product:
sal run --message "Rerun the gauge harvester after fixing its pagination"It takes the same --message a build does and falls back to the commit’s message the same way, since the snapshot it commits is a build’s; a --force run over uncommitted changes is refused without one.
sal run is a debugging command, and it says so in a warning every time it starts.
sal build runs the same tasks as part of every build, so a data product never needs sal run to be complete;
it exists to run a module again while working on it, on top of a build that already committed everything else.
The snapshot it commits is produced by the same operation a build’s is, with the task output the modules produced as the only change.
sal run refuses to run anything unless the data product matches the sources as they stand:
- The Git working tree must be fully committed.
- The table’s latest snapshot must be the one
sal buildtagged with the commitHEADpoints at.
If either check fails, run sal build again (committing anything it wrote, such as newly pinned
vocabularies in .sal/config.jsonld) and then sal run. A project that declares no module tasks
is an error, since there is nothing to run.
Like sal build --force, sal run --force skips both checks and should only be used for test or
debugging runs.
sal run works under the same progress and log panes as sal build, and takes the same --no-tui.
sal construct
Section titled “sal construct”Runs every SPARQL CONSTRUCT query in the project’s sparql/ directory against the last build and writes what each one constructs to .sal/constructed:
sal constructsparql/ known-by.rq stations/nearby.rq.sal/ constructed/ known-by.ttl stations/nearby.ttlsal construct is a debugging command: it only reads the table, and never changes it or creates a snapshot.
sal build runs the same queries as part of every build and is what commits the triples they construct.
.sal/constructedis wiped at the start of every run, so it never holds the output of a query that has since been renamed or removed.- The output is Turtle, written with the prefixes the query declares. It is smaller than the same graph as JSON-LD and needs no
@contextresolved to write or read it. - The directory is gitignored.
sal initadds it to.gitignore; in a project whose.gitignoredoes not cover it, the directory is given a.gitignoreof its own instead, so that a tracked file is never changed by a build. - It reads the table the last build committed, which already holds what the queries constructed then. A query whose pattern matches its own output therefore constructs more here than it did in the build, which ran it before those triples existed.
sal query
Section titled “sal query”Opens an interactive SQL shell with a triples view over the built Iceberg table.
DuckDB is linked into sal, so nothing has to be installed alongside it.
sal query
The shell opens on the requested info query and leaves the triples view there to
explore. Ctrl + R runs the editor’s statement, Ctrl + H lists the other keys,
and Ctrl + D exits.
A project that imported a data product with sal import oci://... gets a view per imported table alongside
triples, plus an imports view stacking them all.
Info modes:
head: show the first rows fromtriples.properties: show Iceberg table properties.snapshots: show Iceberg snapshots, newest first: the snapshot’s ID, parent, timestamp, and operation, the triples it added and removed, the message the build recorded, the Git commits the build tagged it with (git_commits), and the metadata file it was committed in (metadata_file, the lowest version naming it as current, whichiceberg_scanreads the table at that snapshot with; for anhttps://table, whose metadata directory cannot be listed, only the current snapshot has one).column-stats: show Iceberg column statistics.
To compare snapshots:
sal query --snapshot-diff latestsal query --sparql opens the same shell in SPARQL mode instead, translating each query to SQL over that view.
See SPARQL Query Engine for how the translation works and which SPARQL constructs it supports.
sal get
Section titled “sal get”Looks up the RDF resources inside a built data product.
Where sal query is about the Iceberg table that stores the triples, sal get is about the RDF the table describes.
sal get vocabularies is the exception: it reads the pinned vocabulary and project ontology nodes in .sal/config.jsonld rather than the built data product.
By default, classes, datatypes, instances, properties, and shapes list only the resources the project itself defines: the subjects named under the project base, which comes from the Git remote the same way sal build resolves the project’s own relative terms.
An imported ontology or a module task contributes resources under its own namespace, and those are left out until --all is given:
sal get instances --allstatements and vocabularies always list every namespace and have no --all flag.
sal get classes
Section titled “sal get classes”Lists every class the data product declares, with the annotations each one carries:
sal get classesclass rdfs:label rdfs:commenthttps://w3id.org/sal/salmodule#NodeProc... Node Processor A task that reads nodes and writes nodeshttps://w3id.org/sal/salmodule#Task Task A unit of work a module runsA class is a subject declared to be an rdfs:Class or an owl:Class, so a data product that only types its resources with a vocabulary it does not itself carry lists none; sal get instances is what reports the classes resources are typed with.
A class declared to be both is listed once.
Only the classes named under the project base are listed unless --all is given, so the classes of an imported ontology, like the SAL module vocabulary above, only appear with sal get classes --all.
rdfs:label and rdfs:comment are optional; a column that no class states is left out of the table entirely.
sal get datatypes
Section titled “sal get datatypes”Lists every datatype the data product declares, with the annotations each one carries:
sal get datatypesdatatype rdfs:label rdfs:commenthttps://w3id.org/sal/salmodule#inbou... Inbound Listener Literal representing a [host:]<port>https://w3id.org/sal/salmodule#outbo... Outbound Endpoint Literal representing a URL or <host>:<port>A datatype is a subject declared to be an rdfs:Datatype, so a data product that only holds instance data lists none.
Only the datatypes named under the project base are listed unless --all is given, so the datatypes of an imported ontology, like the SAL module vocabulary above, only appear with sal get datatypes --all.
rdfs:label and rdfs:comment are optional; a column that no datatype states is left out of the table entirely.
Note that this lists the datatypes a data product defines, not the datatypes its literals are tagged with.
The built triples table stores the lexical value of a literal rather than its datatype IRI, so ^^xsd:date and friends cannot be listed back out of it.
sal get instances
Section titled “sal get instances”Lists the resources the project instantiates, with the class each one is typed with:
sal get instancesinstance classhttps://github.com/cgs-earth/sal-demo/Andrew https://schema.org/Personhttps://github.com/cgs-earth/sal-demo/MyRandPeople salmodule://github.com/cgs-earth/sample-salmodule/RandomPeopleWhere sal get classes lists the classes the data product defines, this lists the resources typed with a class, whether or not the class is defined in the data product.
A resource typed with several classes is listed once per class.
Only the resources named under the project base are listed by default, which includes whatever a module task
materialized under relative IRIs. The resources a module task named with absolute IRIs, or an imported data
product carries, are named under other namespaces and only appear with --all:
sal get instances --allinstance classhttps://geoconnex.us/ref/states/66 http://schema.org/Statehttps://geoconnex.us/ref/states/69 http://schema.org/Statehttps://github.com/cgs-earth/sal-demo/Andrew https://schema.org/Personhttps://github.com/cgs-earth/sal-demo/MyRandPeople salmodule://github.com/cgs-earth/sample-salmodule/RandomPeopleThe class is not required to be declared an rdfs:Class or an owl:Class in the data product, since a data product commonly types its resources with a vocabulary it does not itself carry.
What is left out is the other direction: a subject that is itself an rdfs:Class, owl:Class, rdf:Property, owl:ObjectProperty, owl:DatatypeProperty, owl:AnnotationProperty, rdfs:Datatype, or owl:Ontology describes the schema rather than instantiating it, so it is not reported as an instance.
sal get properties
Section titled “sal get properties”Lists every property the data product declares, with the type it was declared with:
sal get propertiesproperty typehttps://w3id.org/sal/salmodule#... http://www.w3.org/2002/07/owl#AnnotationPropertyhttps://w3id.org/sal/salmodule#... http://www.w3.org/2002/07/owl#DatatypePropertyhttps://w3id.org/sal/salmodule#... http://www.w3.org/2002/07/owl#ObjectPropertyA property is a subject typed rdf:Property, owl:ObjectProperty, owl:DatatypeProperty, or owl:AnnotationProperty, so type is what the property was declared to be rather than something inferred from how it is used.
A property declared to be more than one of them is listed once per type, the way sal get instances lists a resource once per class it is typed with.
Only the properties named under the project base are listed unless --all is given, so the properties of an imported ontology, like the SAL module vocabulary above, only appear with sal get properties --all.
Note that this lists the properties a data product defines, not the predicates its statements use, so a data product that only holds instance data lists none.
It is also unrelated to sal query --info properties, which reports the properties of the Iceberg table rather than the RDF the table holds.
sal get shapes
Section titled “sal get shapes”Lists every SHACL shape the data product declares, with the annotations it carries and the class it targets:
sal get shapesshape rdfs:label rdfs:comment rdf:type sh:targetClasshttps://github.com/cgs-earth/sal/PersonShape Person Shape Every person described here is named. http://www.w3.org/ns/shacl#NodeShape https://schema.org/Personhttps://github.com/cgs-earth/sal/PlaceShape Place Shape A place is named and carries a geometry. http://www.w3.org/ns/shacl#NodeShape https://schema.org/Placehttps://github.com/cgs-earth/sal/PersonName Person Name A person is named exactly once. http://www.w3.org/ns/shacl#PropertyShapeEvery column but shape reports the object of a predicate, and is named with the prefixed form of that predicate, so the table says which term each value was read from rather than leaving label to stand for whichever of the several labelling predicates a vocabulary offers.
shape is the subject the other columns are read from, so it is not named this way.
A shape is a subject typed sh:NodeShape or sh:PropertyShape, so rdf:type is what the shape was declared to be rather than something inferred from its properties.
A shape declared to be both is listed once per type, and a property shape written inline as a blank node is listed under the blank node identifier it was given.
A shape the project defines itself is named under the project base, which comes from the Git remote, the same way sal build resolves any other relative term the project writes.
A shape that arrives from an imported ontology keeps the namespace that ontology gave it, and is listed only with sal get shapes --all.
rdfs:label, rdfs:comment, and sh:targetClass are all optional; a column that no shape states is left out of the table entirely.
sh:targetClass is the one a shape can state more than once, and a shape targeting several classes is listed once per class, the way sal get instances lists a resource once per class it is typed with.
sal get statements
Section titled “sal get statements”Lists the statements of the data product, one row per triple:
sal get statements --limit 3subject predicate object type languagehttps://geoconnex.us/ref/dams/1078 http://www.w3.org/1999/02/22-rdf-syntax-ns#type http://www.w3.org/ns/dcat#Datasethttps://geoconnex.us/ref/dams/1078 http://www.w3.org/2000/01/rdf-schema#label Bureau of Reclamation Dam 1078 http://www.w3.org/1999/02/22-rdf-syntax-ns#langString enhttps://geoconnex.us/ref/dams/1078 http://purl.org/dc/terms/created 2026-06-02 http://www.w3.org/2001/XMLSchema#dateThe object column is the object of the triple whichever typed column of the table holds it, with a geometry rendered as WKT.
type is the datatype IRI of a literal object and language is the language tag of a language-tagged string; both are empty for an IRI or blank node object, and language is empty for any literal that carries no tag.
--limit bounds how many statements are listed, and without it every statement is.
The rows stream to standard out in table order, so a data product larger than memory can still be listed in full; they are aligned in blocks of 5000 rows rather than across the whole listing.
Use sal export instead to get the statements back as RDF.
sal get vocabularies
Section titled “sal get vocabularies”Lists every vocabulary the project knows about from .sal/config.jsonld: the vocabularies sal build and sal validate have pinned, unioned with what sal import has recorded with owl:imports on the project ontology node, with whether each one is imported:
sal get vocabulariesvocabulary version format importedhttps://schema.org/ urn:sha256:2c8... application/ld+json yeshttps://www.w3.org/ns/dcat# urn:sha256:9f1... text/turtle nooci://ghcr.io/cgs-earth/example:latest yessalmodule://github.com/cgs-earth/example urn:git-commit-hash:9a1... application/ld+json yesversion and format come from the pin a build or validation records the first time it resolves a prefix or an import against a vocabulary. An oci:// import is never dereferenced as a document to pin, since the artifact it names is not a vocabulary document, so it is still listed as a vocabulary here but with no version or format. A salmodule:// import is dereferenced by building the module and pinned by the module repository’s git commit hash rather than a document digest, the same as a salmodule:// vocabulary.
sal describe
Section titled “sal describe”Shows every statement the data product makes about one subject:
sal describe https://github.com/cgs-earth/sal/Bobpredicate objecthttp://schema.org/jobTitle Professorhttp://schema.org/name Jane Doehttp://schema.org/url http://www.janedoe.comhttp://www.w3.org/1999/02/22-rdf-syntax-ns#type http://schema.org/PersonThis is the <subject> ?p ?o pattern, so it is a filter on the subject column rather than a SPARQL query.
A subject with no scheme is a term the project defined itself, so it is resolved against the project base the same way sal build resolves a relative term in the project’s RDF. In a checkout of https://github.com/cgs-earth/sal, the command above can be written as:
sal describe BobThe project base comes from the git remote, so a relative subject only works inside a checkout that has one.
A prefixed name such as schema:Bob is not expanded; a scheme is what makes a subject absolute, and schema: is one.
An IRI copied out of Turtle or a SPARQL pattern can be passed with the angle brackets it is written in:
sal describe '<https://geoconnex.us/ontologies/method/pastor>'A subject with no statements is reported rather than printed as an empty table.
sal export
Section titled “sal export”Streams every triple in the built data product to standard out as N-Triples, <subject> <predicate> <object> . one line per row:
sal export > data.ntThis is meant for feeding a data product into another RDF-aware program rather than for reading directly; pipe it into anything that accepts N-Triples or N-Quads. For instance, you can use rdflib with sal like the following to convert triples to CSV.
sal export | uv run --with rdflib python -c 'import sys, rdflib; g=rdflib.Graph(); g.parse(sys.stdin, format="nt"); print(g.query("SELECT * WHERE { ?s ?p ?o } LIMIT 10").serialize(format="csv").decode())'triple_hash is left out, since it identifies a row rather than being part of the triple it names.
Each object is restored to its original shape from the typed object column that holds it, retyped with the exact datatype IRI the object_type column recorded at build time (see Data Layout):
- An IRI object comes back as
<...>. - A typed literal comes back with its original datatype —
"5"^^xsd:byteand"5"^^xsd:integerare stored in different columns and both round-trip as themselves, and a datatype without a typed column, such asxsd:date, was stored as a string alongside its datatype and comes back typed too. A numeric or dateTime value’s lexical form is the column’s canonical rendering (1e3comes back as1000.0; a stored dateTime comes back in UTC), but the datatype is always exact. - A geometry literal comes back typed
^^<http://www.opengis.net/ont/geosparql#wktLiteral>, with its WKT text restored from the geometry the table stores. Any GeoSPARQL CRS prefix the original literal had is not restored. - A blank node comes back as
_:.... The table stores every blank node with its_:prefix, so a blank node round-trips exactly in both subject and object position. - An
xsd:stringcomes back as a plain string literal, which is the same RDF term. A language-tagged literal also comes back plain, since the tag itself is not stored.
sal export mirrors the table exactly rather than rewriting anything it reads: a value is written out with whichever N-Triples syntax its stored shape calls for (<...>, _:..., or "..."), but its content is never altered. In particular, IRIs are not resolved against a base — if a subject or object is stored as a relative IRI, it is exported as a relative IRI, which is not valid per the N-Triples grammar but does guarantee the export always says exactly what the table says.
sal serve
Section titled “sal serve”Serves the built triples table as a read-only SPARQL endpoint on port 8080:
sal serveThe endpoint implements the SPARQL Protocol query operation at /sparql.
It accepts GET requests with a query parameter and POST requests using either application/sparql-query or application/x-www-form-urlencoded, and it answers with application/sparql-results+json.
Queries are translated to DuckDB SQL rather than evaluated by a triplestore; SPARQL Query Engine documents that translation and the subset of SPARQL it covers.
The same query operation is available against an earlier version of the table at /v{snapshot}/sparql, where {snapshot} is the ID of an Iceberg snapshot, such as /v7847372623449923428/sparql.
It accepts the same requests and answers the same way as /sparql, but every triple pattern reads the table as it stood at that snapshot, so a query can be pinned to the version of the data product it was written against even after later builds have committed on top of it.
sal query --info snapshots and the Stats tab of --with-ui list the snapshot IDs a table has.
A snapshot the table does not have, or a version that is not a snapshot ID at all, answers 404 saying so; the snapshot is checked on every request, so one committed while the server is running is queryable without a restart.
A query can also name one of these endpoints in a SERVICE clause and subtract it with MINUS, which is how two snapshots are diffed in one query; see Diffing snapshots with SERVICE and MINUS.
It also serves the vocabulary and imported ontology documents the project has pinned, and the files SAL module tasks produced, at GET /blobs/{hash}, where {hash} is the name a document is stored by under .sal/data/blobs: the SHA-256 digest of the document, or the git commit hash of the module for a salmodule:// vocabulary. Either may be given bare or headed by the scheme its owl:versionIRI carries, urn:sha256: or urn:git-commit-hash:, which is stripped. A hash with no matching document answers 404. The endpoint supports HTTP range requests, so a client can fetch part of a document without downloading the whole thing. This route is available with or without --with-ui; the UI’s own Blobs tab, described below, is a thin form over it.
A directory a SAL module task produced sits under .sal/data/blobs/{digest}/ with its files as the task wrote them, so GET /blobs/{digest}/{file} serves each file in it as it is, with a content type from its extension, and a STAC or Zarr client pointed at /blobs/{digest}/ reads it in place. The directory itself is served as a zip archive, named after the file:/// IRI the task gave it, at /blobs/{digest} with or without a trailing slash, and /blobs/prov.jsonld serves the record of every copy. A path that would step outside .sal/data/blobs answers 404. CORS is open on the endpoint, the same as on /stac/, so a STAC browser on another origin can follow the data product’s catalog into a module’s. With --with-ui, only /blobs itself is the Blobs tab; a browser following a link to /blobs/{path} gets the file.
The triples table is also served as an OGC API Features endpoint at GET /ogc, with every RDF subject that has a geometry as a GeoJSON feature under its IRI, the predicates named in the properties parameter as its properties, and the snapshot parameter reading the collection or a feature at any Iceberg snapshot of the table; QGIS or any other OGC API Features client can be pointed at it. This route is available with or without --with-ui; with it, a browser navigating to any of the endpoint’s URLs gets the feature view of the UI’s Geospatial tab, described below, which runs an items or item URL as its query, while a client asking for JSON gets the document.
The STAC catalog sal build writes is served at GET /stac/catalog.json, which /stac and /stac/ also answer with, and its collection at GET /stac/triples/collection.json.
The documents are served exactly as they were written, so the collection’s iceberg:metadata_location is a file:// URL on the machine running the server, which a reader on that machine can pass straight to DuckDB’s iceberg_scan(); see STAC catalog.
The endpoint allows cross-origin reads, so a STAC browser on another origin can open it, and a table built before SAL wrote catalogs answers 404 saying to run sal build.
This route is available with or without --with-ui.
Every request is recorded as an OpenTelemetry trace, with the query it ran under it, when an exporter is configured; see Telemetry.
--with-ui
Section titled “--with-ui”Adds a web UI at / alongside the SPARQL endpoint:
sal serve --with-uiThe UI is a React app compiled into the sal binary, so it works offline and needs no extra install.
It has five tabs:
- Stats: the landing page. A card at the top names the data product, with the title
sal importrecorded on the project ontology in.sal/config.jsonld(the table’s name when there is none) and the table path on one line, gives the triple count, read from the current snapshot’s summary in the Iceberg metadata (total-recordslesstotal-equality-deletes) rather than counted by a scan, so the page opens as quickly on a table of hundreds of millions of triples as on a small one and a small map of the table’s spatial extent, the same envelope/geometries/extentanswers, drawn as a dotted outline on the right with its corners and their frame, CRS84, under it (zoomable, and saying so when the table holds no geometries), and links to the collectionsal buildwrote for the table: STAC JSON opens the/stac/triples/collection.jsondocument itself and STAC viewer the catalog root,/stac/, in the Portolan STAC Browser atbrowser.portolan-sdi.org, so the collection and every catalog a SAL module produced are in view together, which works when that site can reach the server’s origin, such aslocalhost, from the browser. Both are disabled when no catalog has been built. The circular arrow beside them rereads the table. Below the card are the Iceberg snapshots, newest first, each with its timestamp to the minute, the triples it added and removed, the message the build recorded, the Git commit or commits the build tagged it with (several when a later build changed nothing and tagged the snapshot it already had), and a Query column with two buttons: SQL opens the SQL tab on a statement that scans the table at that snapshot withiceberg_scanandsnapshot_from_id, and SPARQL opens the SPARQL tab on a query that reads it through aSERVICEon the server’s own/v{snapshot}/sparqlendpoint; then the vocabulary listingsal get vocabulariesprints, a Storage layout card, and last the table propertiessal query --info propertiesprints. Aurn:sha256:orurn:git-commit-hash:version in the vocabulary listing is a link that opens the document in the Blobs tab, rendered in the page. The layout card reads the Iceberg metadata for what decides how a query performs: how many data files the table has and their average and median row counts, the bytes on disk, how many partitions the files fall in, and how many delete files hold removed triples; a table marking the partition column with its transform and the sort column with its direction and saying, for each column, the worst-case number of files a scan for a single value has to read, the most files whose lowest-to-highest range Iceberg records for the column can admit one value (for the geometry column, the files whose bounding box a query can meet plus those recording neither a box nor a null count proving they hold none), with a filter performance grade of good, fair, investigate, or none (never poor, since reading most files only matters when queries filter on that column, and for a geometry column it is a matter of the statistics written rather than the layout); beside the table an overview pane says what stands out, the files that hold over four times the average, the files that hold under a tenth of the median (the diffs of builds that changed little, whichsal clean --wipeand a rebuild compact away), and the delete files every scan subtracts, and clicking a row replaces it with what a filter on that column performs like, the worst-case share of the files as a bar, the reasoning, the range the files record, and the query shape that takes that path, since a query constrained on the partition or sort column is answered from a few files while one constrained on a column whose ranges overlap everywhere reads them all. Under all of that is the File layout, every file with its partition, kind, rows, size, and the Iceberg snapshot that wrote it, its id with the build’s message after it, open by default and foldable, with each heading sorting the list by that column, again to reverse; the per-file column statistics themselves are whatsal query --info column-statsprints. - SPARQL: a YASGUI editor pointed at the local
/sparqlendpoint. A Prefixes button beside Examples lists every vocabulary the project pins, the same ones the Stats tab shows, each with the prefix it is known by (the one its own document binds, else the conventional one, else the last segment of its namespace), how many terms its pinned document defines, and whether it is imported, and after them the three the query engine defines whether or not the project pins anything, marked built in:geof:with the GeoSPARQL functions the engine answers,uom:with the unitsgeof:distancetakes, andxsd:with the XML Schema datatypes; a project that pins one of those namespaces itself sees its pinned document instead. Choosing one adds itsPREFIXline to the query, Add all adds every one not yet declared, and a vocabulary the query already declares under any label is marked rather than added twice. Once a prefix is declared, typing it and a colon suggests the terms of that vocabulary as it was pinned, read from the document under.sal/data/blobsrather than from a public registry, so asalmodule://ontology completes like any other:schema:naoffersschema:name,geof:sfoffers the Simple Features relations, matching ignores case, each suggestion is tagged as a class or a property, and in a predicate position properties are listed first while afteraclasses are. A prefix typed in a query without its declaration is declared automatically when it names one of those vocabularies, and on aPREFIXline they are offered as completions. A Show RDF Definitions box, on by default and remembered by the browser, docks a pane down the right of the editor, the editor’s full height, narrowing the editor to make room rather than covering it. With the caret on such a name (schema:Person, say), with the name selected, or with it highlighted in the completion list as the list is walked with the arrow keys, the pane describes the term from the same pinned document: the IRI it expands to, whether it is a class or a property, and what the document states about it withrdfs:label,rdfs:comment,skos:definition, a description or note,rdfs:subClassOf,rdfs:subPropertyOf,rdfs:domain,rdfs:range, schema.org’sdomainIncludesandrangeIncludes,owl:deprecated, andrdfs:seeAlso, whichever are present and at most five values each, English or untagged literals first; with nothing to describe it says what to do. Unticking the box removes the pane and gives the editor its full width back. YASGUI’s own completers, which asked lov.linkeddata.es and prefix.cc on every keystroke, are off. The Inherited classes in use and Labels through subproperties samples are property paths over whatever class and property hierarchies the table holds, the project’s own statements and the ontologies it imports; neither names a term of any particular vocabulary. A ? button in the panel header opens a short note on what the tab and its controls do. A Show SQL toggle beside it opens a read-only pane with the DuckDB SQL the query translates to, kept up to date as the query is edited, so what the endpoint runs under the hood can be read next to the SPARQL that produced it. A strip in the pane’s header switches between that SQL and the plans DuckDB would run it as, asked of/api/sql/explainfor the statement showing and drawn as a tree of operators, the root first and the scans under it, each with what DuckDB says about it (the table a scan reads, the expressions a projection computes, the filters pushed into a scan) and the rows it expects to produce, folding on its heading: Logical, the plan the binder builds from the SQL, Optimized, that plan after the optimizer has pushed filters down and reordered joins, and Physical, the operators that run. A plan is asked for only while its view is showing, and a Copy button copies the SQL or the plan as JSON. The pane sits under the editor and its results and is as tall as what it shows, wrapping long lines of SQL rather than cutting them off; a query the translator rejects shows the error/sparqlwould answer with instead. The toggle and the view are off and SQL by default and remembered by the browser. When a result holds WKT or GeoJSON, a map button beside the share button in the result header opens the Geospatial tab’s map view on it. The sample chips include Features near a point, Inside a buffer, Largest polygons, and Centroids as GeoJSON, which use the GeoSPARQL distance, buffer, measure, and serialization functions, Two steps up the hierarchy, Linked either way, and Everything but typing, which are a repeated sequence path, a repeated alternative of a predicate and its inverse, and a negated property set, Slugs and fresh identifiers forENCODE_FOR_URIandUUID(), Added since previous snapshot and Removed since previous snapshot,MINUSqueries over aSERVICEon the table’s own previous snapshot that list the triples one has and the other lacks, and Pinned blobs, which lists everyowl:versionIRIthe table refers to with itsrdfs:label, the same listing the Blobs tab shows. - SQL: a DuckDB editor over the same
triplesviewsal queryopens, with sample queries andCtrl/Cmd+Enterto run. When a result holds WKT or GeoJSON, a map button beside Copy CSV opens the Geospatial tab’s map view on it. - Geospatial: two views under one header, switched by the strip beside the title. The map view is a MapLibre map of the
object_geometrycolumn, as one of two things. It draws the geometry the last SQL or SPARQL query returned — any column holding WKT or GeoJSON becomes a feature, and the other columns of its row become the properties shown when the feature is clicked; a Show dropdown choosing between the results, the feature view’s last run among them, and the box query appears once one of the results holds geometry, and each editor’s own map button opens the view on its result — or everything inside a bounding box. While a result is drawn, the box controls are grayed out and a click on the map queries nothing, so the result is not replaced by accident; choosing the box query in the dropdown unlocks them. Clicking the map queries a box around that point sized to the viewport, a square on screen that fits inside it; the box’s corners can also be typed in, are outlined on the map, and can be opened as a GeoSPARQL query in the SPARQL tab, and a line under the button says how many features the box returned and how long it took. Two buttons at the map’s top left zoom to the spatial extent of the whole table and outline it, and a control at the top right takes the map full screen. The feature view is a query builder over the OGC API Features endpoint at/ogc, for looking at individual features, in two panes: the builder names the Iceberg snapshot to read and optionally one to compare with, one feature by its IRI or a page of them, and the filters, the predicates to carry as properties and a class to keep, both completed from the pinned vocabularies by a term box that offers the prefixes and then narrows the vocabulary’s terms as the name is typed, the way the SPARQL editor completes a term. A Show queries box beside Run lists the requests it would make, each with a copy button so it can be handed to QGIS, and nothing is fetched until Run; the results pane then lists the features five at a time, each with buttons that copy its own URL and its GeoJSON, and selecting a feature shows its properties under the list, side by side at both snapshots with the differing rows marked when a second snapshot was compared, and a map of that one feature under them. See the feature view. The basemap is fetched from OpenFreeMap, so it is blank offline; the features still draw. - Blobs: the pinned blobs. The tab opens on a listing of every blob the triples table refers to by an
owl:versionIRI, the vocabularies the Stats tab lists and the files and directories SAL module tasks handed over, asIRI | hash | modified, where the IRI is the name the blob had before it was pinned, a vocabulary’s namespace or thefile:///IRI a module task wrote, and modified is thedcterms:modifiedthe table records for it, when a vocabulary was pinned or the mtime of a copied file, blank when there is none. A filter box in the panel header keeps the rows whose IRI or hash contains what is typed, and clicking a column heading sorts by that column, again to reverse. The list shows the first 100 and says so when the table refers to more, pointing at the SQL and SPARQL tabs for the rest; the filter and the sort act on those rows. Clicking a row switches the tab to a view of that one blob: its text, pretty printed when it is JSON, in a block that scrolls inside the page, or, for a blob that is not text or is larger than 4 MB, a note instead; two icon buttons at the top right copy the text to the clipboard and download the blob through the browser’s normal save flow, and the back arrow returns to the listing. The view is its own URL,/blobs?hash=<digest>, which the version links on the Stats tab and in query results open, so a rendered blob can be linked to directly.
Each tab has a URL of its own — /stats, /sparql, /sql, /geospatial, and /blobs — so a tab can be linked to rather than only clicked to, and the browser’s back button moves between them; /ogc and /geospatial?view=features open the Geospatial tab on its feature view, and /map, the tab’s path before it was renamed, still opens it.
The path of the table being queried sits at the right of the header, marked local while it is the project’s own.
Clicking it opens an input for the root of a triples table on object storage, such as the gs://bucket/sal/triples that sal upload wrote, and the check mark (or Enter) points every tab at that table instead, while the cross (or Escape) closes the input (the browser’s form history offers the tables entered before): the SPARQL endpoint, the SQL and stats APIs, and the map all read it, so an uploaded data product can be queried and its stats read without deploying another sal serve for it.
The header then marks the table remote.
Only s3://, gs://, r2://, az://, and https:// are accepted; a path on the machine running the server is refused, since anyone who can reach the UI could otherwise point it at any file there.
Name the table in the form sal upload wrote it with: a table uploaded to https://storage.googleapis.com/<bucket>/... has its data file paths percent-escaped for HTTPS, so reading it as gs://<bucket>/... escapes them a second time and every data read fails with a 404, while reading it at the https://storage.googleapis.com URL works.
The Cloud console’s https://storage.cloud.google.com/... link to a bucket is a web page behind a login, not the bucket, and is refused with the two forms that would work.
The table is opened before anything switches, so a location DuckDB cannot read as a triples table reports its error and leaves the current table in place, and a table built by an older sal without the typed object columns is refused the way sal query refuses it.
Leaving the input empty returns to the local table.
The switch is for the whole server, not the one browser tab: every request after it reads the new table, including a client of the /sparql endpoint.
What is on disk stays the project’s: the Blobs tab, /blobs, and /stac/ keep serving the local blob store and catalog, the Stats tab lists no vocabularies for a remote table since they are read from .sal/config.jsonld, and the imported data products’ views are not registered for it.
DuckDB reads a bucket with whatever credentials its httpfs extension finds in the environment, so a private bucket needs them set before sal serve starts.
Two of those names, /sparql and /blobs, are also endpoints.
A browser navigating to either gets the UI; anything else — curl, a SPARQL client library, the UI’s own fetch() calls — gets the endpoint, as does any request carrying a SPARQL Protocol query parameter, whatever asked for it.
The SQL and SPARQL tabs each have a Copy link button, next to Run on the SQL tab and at the right of the results header on the SPARQL tab.
It copies a link to that tab with the editor’s current query URL encoded into a q parameter, such as http://localhost:8080/sql?q=SELECT%20*%20FROM%20triples.
Opening the link loads that query back into the editor — into a new Shared query tab on the SPARQL side, so it never overwrites what YASGUI restored.
q is deliberately not the SPARQL Protocol’s query, which stays reserved for callers of the endpoint.
Enabling the UI also exposes the JSON endpoints it reads:
POST /api/sqlwith a{"sql": "..."}body runs a DuckDB statement and returns its header and rows. Results are capped at 1000 rows, and the response message reports the full count when it truncates.POST /api/sparql/translatewith a{"query": "..."}body returns{"sql": "..."}, the DuckDB SQL the/sparqlendpoint would run that query as, without running it. A query the translator does not support answers400with the same error/sparqlwould.POST /api/sql/explainwith a{"sql": "..."}body returns the plans DuckDB would run the statement as,{"logical": [...], "optimized": [...], "physical": [...]}, each the roots of a tree of{"name", "details", "children"}operators wheredetailsis what DuckDB’sEXPLAINwrites about the operator, in order, as{"key", "values"}pairs. The statement is bound and optimized, which reads the table’s Iceberg metadata, but never run; one DuckDB cannot bind answers400with its error.GET /api/statsreturns the counts and Iceberg metadata shown on the Stats tab, the project ontology’stitleanddescription(empty for a remote table or a project that never ransal import), themoduleslist the build recorded in thesal.salmodulestable property, and aslayoutthe storage layout the card draws:partitioningandsortOrderfrom the current metadata file,partitions,dataFilesanddeleteFilessummaries (count,rows,bytes,averageRows,medianRows,minRows,maxRows), theoutliersamong the data files (each with itsfile, akindofsmall, under a tenth of the median, orlarge, over four times the average, and itsratioto that reference), per column undercolumnsthefilesWithBounds, themaxFilesPerValueone value can fall in, thenulls, and the overalllowerandupperbounds, andfiles, every live file with itspathunder the table root,partition,kind,rows,bytes, andsequenceNumber. A table whose metadata cannot be read answersnullthere with the reason inlayoutError, and the rest of the stats as usual.GET /api/tablereturns{"remoteTablePath": "..."}, the table on object storage the server’s queries read, empty when they read the project’s own.PUT /api/tablewith the same body points them at that table, or back at the local one when it is empty, and answers the location now in use; a location that is not ans3://,gs://,r2://,az://, orhttps://URL, or that DuckDB cannot read as a triples table, answers400and leaves the current table in place.GET /api/vocabulariesreturns{"vocabularies": [...]}, every vocabulary the project pins in.sal/config.jsonldwith itsprefix,namespace,version,format, whether it isimported, the local names its pinned document defines under the namespace asclasses,properties, andothers, and asstatementswhat the document says about each of those names with the descriptive properties the term panel shows (each{"predicate", "value", "iri", "language"}, predicate and IRI value written as prefixed names where a prefix is known), which the SPARQL tab’s Prefixes dialog, completions, and term panel read. A vocabulary whose pinned document cannot be read is listed with anerrorand no terms; nothing is fetched. After the pinned vocabularies come the engine’s built-in ones,geof:,uom:, andxsd:, each marked"builtin": truewith noversion, with the functions, units, and datatypes the engine answers as their terms and a comment on each saying what it does; one the project pins under the same namespace is listed as pinned instead. A remote table lists only the built-ins, since the pins are the project’s.GET /api/blobs?limit=returns the firstlimitblobs the triples table refers to, 100 by default and at most 1000, as{"blobs": [{"iri": ..., "hash": ..., "modified": ...}], "truncated": ..., "sql": ...}: every subject with anowl:versionIRIof theurn:sha256:orurn:git-commit-hash:form, each with itsrdfs:label, thefile:///IRI for a copied file or directory, and itsdcterms:modifiedwhen it has one (left out otherwise).sqlis the DuckDB statement that lists them, for running with a higher limit.GET /geometries?limit=&offset=&bbox=returns up to 1000object_geometryvalues at a time as GeoJSON, each feature carrying thesubject,predicate, and WKTobjectof its triple.bbox=minX,minY,maxX,maxYkeeps only the geometries intersecting that box.GET /geometries/extentreturns the bounding box of every geometry in the table as a GeoJSON feature: itsgeometryis the envelope, itsbboxthe four corners, and itsproperties.geometrieshow many geometries it covers. A table with no geometries answers anullgeometry.
/api/sql runs arbitrary DuckDB statements against your machine and /api/table points every query at a bucket a caller names, so only enable --with-ui on a network you trust. Nothing the server answers clones or builds a SAL module; that happens only in sal build, sal validate, and sal salmodule inspect, run from the command line.
--slow-query-after
Section titled “--slow-query-after”Every query starts on one DuckDB database. A query still running after --slow-query-after (5 seconds by default) is cancelled there and run again from the start on a second database, which gets a quarter of the cores and a quarter of the memory budget, while the first gets every core and half of it. DuckDB shares a database’s threads among the queries running on it with no notion of priority, so without this one scan of the whole table makes every lookup arriving behind it wait. With it, quick queries only ever wait behind the first few seconds of a heavy one, and the heavy queries compete with each other on the second database. A query that is moved pays those few seconds again. --slow-query-after 0 runs every query on the one database. Statements that stream their rows (sal export and the CONSTRUCT queries of a build) and plans asked for by /api/sql/explain always run on the first database.
sal serve --data /mnt/sal --slow-query-after 10sServing an uploaded copy
Section titled “Serving an uploaded copy”--data serves a copy of a project’s .sal/data instead of the project the current directory belongs to, so no project, git repository, or DuckDB catalog is needed where the copy sits, such as a container with a bucket mounted into it:
sal serve --data /mnt/salThe directory is any of the three layouts an upload or a copy of .sal/data has, and sal serve finds the table and the files beside it for each:
| Layout | Where the table is | blobs/, stac/, config.jsonld |
|---|---|---|
a copy of .sal/data, or a bucket-root upload (sal upload --bucket gs://my-bucket/) |
<project>/triples, two levels down |
at the directory’s top, beside <project>/ |
an upload to an explicit table root (--bucket gs://my-bucket/sal/triples, or a file:// destination) |
the directory itself | only what the upload carried: the table, and config.jsonld |
The table is the one directory, at any depth, holding a metadata/ directory with a *.metadata.json file; tables under blobs/ and imports/ are not it, and more than one table is an error. blobs/ and stac/ are looked for beside the table’s namespace directory and then upward to the directory named. The table is read through DuckDB’s iceberg_scan, iceberg_metadata, and iceberg_column_stats with allow_moved_paths, so the gs:// paths its uploaded metadata records need no rewriting (sal rewrite is not needed) and no credentials or network.
sal upload also copies the project’s .sal/config.jsonld to the top of the upload. A served data directory reads it for the project’s title and description and for the vocabularies the project pins, which the Vocabularies tab and /api/vocabularies list from the blobs/ beside it; there is no project above the directory to read them from otherwise. A copy without it, such as one uploaded by an older sal, lists only the built-in vocabularies and logs a warning saying so. This is what the Cloud Run service sal terraform deploys runs.
sal push
Section titled “sal push”Publishes .sal/data as an OCI artifact:
sal push ghcr.io/my-org/my-data-product --username "$OCI_USERNAME" --password "$OCI_PASSWORD"SAL uploads generated data files as OCI layers and annotates the artifact with the source Git remote and current commit hash.
The artifact’s org.opencontainers.image.description names the remote and commit and ends with the --message of the build that committed the table’s latest snapshot, so a registry’s listing says what the latest build changed.
The project’s own description, from the project node of .sal/config.jsonld, is annotated as sal.description, which is what sal pull and sal clone initialize the project with.
See Publishing Data.
In a terminal, the push works under the progress and log panes: checking which snapshots the remote already has, uploading the data product, and pushing the manifest.
The upload phase counts the files and bytes sent out of the total, with a bar and the average speed so far, as the registry reads them.
--no-tui writes the log to stderr instead, where the upload reports every five files.
--parallel is how many files are uploaded at once, 16 by default; most files of a data product are small, so the latency of each request to the registry counts for more than bandwidth, and more in flight is faster.
sal clone
Section titled “sal clone”Restores a published OCI artifact and its source repository:
sal clone ghcr.io/my-org/my-data-product:latestSAL reads the artifact metadata, clones the recorded source repository, checks out the recorded commit, runs sal init with the description the artifact carries, and restores the artifact layers into .sal/data.
In a terminal, those are the phases of the progress and log panes it works under, and the last one counts the files and bytes pulled out of the total, with a bar and the average speed so far, as they arrive; --no-tui writes the log to stderr instead.
--parallel is how many files are pulled at once, 16 by default, as for sal pull.
Use --destination to choose the local clone path.
sal pull
Section titled “sal pull”Pulls data from an OCI artifact.
It uses the same artifact retrieval command shape as sal clone.
sal pull ghcr.io/my-org/my-data-product:latestOnly an artifact holding snapshots the local data product lacks is pulled; one that holds the same snapshots, or fewer, is skipped with a message saying so, and the progress pane’s summary marks the pull as up to date, nothing to pull rather than as a skipped phase.
sal pull does not need sal init first.
Run in an empty directory, it initializes the directory as a SAL project for the artifact from what the manifest records: a git repository whose origin is the source repository the artifact names (org.opencontainers.image.source), so the data product sits under the same project name and base it was built with, initialized with the description the artifact carries (sal.description, the project’s own description as sal init recorded it; an artifact pushed before that was recorded gets one naming the registry repository).
No source is checked out, so the directory holds the data product and nothing to build; sal clone is what restores the sources with it.
A directory that is neither a SAL project nor empty is refused.
In a terminal, the pull works under the progress and log panes: fetching the manifest, initializing the project when there is none, then pulling the data product, which counts the files and bytes pulled out of the total, with a bar and the average speed so far, as they arrive.
--no-tui writes the log to stderr instead, where the pull reports every five files with the speed.
A file whose download fails partway, as when the registry or the CDN it redirects to drops the connection on a long pull, is fetched again from the start, up to four attempts with a wait that doubles from one second, and only the attempt that succeeds counts toward the bytes shown; the pull fails once a file has failed four times.
--parallel is how many files are pulled at once, 16 by default; most files of a data product are small, so the latency of each request to the registry counts for more than bandwidth, and raising it is what speeds a pull up.
sal upload
Section titled “sal upload”Uploads the built data product to an object store:
sal upload --bucket gs://my-bucket/sal/triplesSAL stages a temporary copy, rewrites staged Iceberg metadata to point at the target location, then uploads data and metadata in reader-friendly order. The project’s .sal/config.jsonld, which sits beside .sal/data, is uploaded at the top of the destination so sal serve --data can name the project and list its pinned vocabularies; a bare bucket (gs://my-bucket/) gets the whole .sal/data layout, <project>/triples/ with blobs/ and stac/ beside it.
See Publishing Data.
sal rewrite
Section titled “sal rewrite”Rewrites local Iceberg metadata so a copied table can be read from a new table root:
sal rewrite --new-table-root gs://my-bucket/sal/triplesThis command changes metadata references only.
It does not rewrite Parquet data files.
It was sal edit before that name went to the module ontology form.
sal terraform
Section titled “sal terraform”Writes a Terraform configuration into terraform/ that serves the built data product from Google Cloud: a Cloud Storage bucket holding the copy of .sal/data that sal upload writes, and a Cloud Run service running sal serve over it. See Publishing Data.
sal terraform --project my-gcp-projectmake apply # terraform init && terraform applymake upload # sal upload --bucket gs://<the bucket>/The bucket is mounted into the container with Cloud Storage FUSE, so sal serve --data reads the Iceberg table as local files, the service account’s read access to the bucket is the only credential, and the bucket and the service sit in one region. The defaults are small on purpose, one CPU, 2 GiB, no instance kept warm, at most two, so an idle deployment costs nothing beyond the bucket, and every one is a variable in variables.tf. The service is public by default and serves the SPARQL endpoint, the STAC catalog, and the blob store, but not the browser UI, whose SQL endpoint runs arbitrary DuckDB statements; with_ui = true turns it on. --region picks the region, --image the sal image, and --dir the directory; --project records the Google Cloud project ID in terraform.tfvars, which must be filled in before make apply otherwise. Files the directory already holds are left alone unless --force is given. sal init --with-iac writes the same configuration when a project is created.
sal terraform only writes files; nothing is created until terraform apply runs.
sal clean
Section titled “sal clean”Removes or reshapes local build artifacts.
Use --wipe to delete the local data product, or --squash to condense local snapshots ahead of a remote artifact.
--wipe also deletes .sal/config.jsonld along with the vocabulary documents its pins name,
the files and directories SAL module tasks handed over together with the .sal/data/blobs/prov.jsonld that records them,
and any data products pulled under .sal/data/imports,
putting the project back to the state it was in before anything was built or imported.
The confirmation prompt names .sal/config.jsonld when it exists, since it is a file the project keeps in Git rather than a build artifact.
Run sal import again to recreate the ontology; the next sal build pins the vocabularies again.
sal salmodule
Section titled “sal salmodule”Outputs SAL module information.
The ontology subcommand prints SAL’s ontology information, and run runs a SAL project.
See the SAL Module TTL Spec for the Turtle source.
The inspect subcommand prints the ontology that a remote module publishes:
sal salmodule inspect salmodule://github.com/adplincinst/sample-salmodule-1SAL clones the module’s repository, builds the Dockerfile in its root, and runs the module’s ontology command, printing the JSON-LD it returns.
Docker’s layer cache makes inspecting an unchanged module cheap after the first build.
The salmodule:// scheme is optional, so adplincinst/sample-salmodule-1 and the repository’s HTTPS URL both work.
A host is only needed for modules that are not on GitHub.
sal test
Section titled “sal test”Reserved for tests on built SAL data products. This command is not yet implemented.

