#Querying

WWKG implements the SPARQL query language with extensions for branching, history, and delta queries.

#Basic queries

#SELECT

wwkg client query "SELECT ?name ?email WHERE {
  ?person <http://example.org/name> ?name ;
          <http://example.org/email> ?email .
}"

#ASK

Returns true or false:

wwkg client query "ASK WHERE { <http://example.org/Alice> ?p ?o }"

#CONSTRUCT

Returns an RDF graph:

wwkg client query "CONSTRUCT {
  ?person <http://example.org/label> ?name .
} WHERE {
  ?person <http://example.org/name> ?name .
}"

#DESCRIBE

Returns all known triples about a resource:

wwkg client query "DESCRIBE <http://example.org/Alice>"

#Output formats

wwkg client query "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10" --format tsv

#Query plans

Use explain to inspect how WWKG will execute a query without running it:

wwkg client explain "SELECT ?name WHERE {
  ?person <http://example.org/knows> <http://example.org/Alice> ;
          <http://example.org/name> ?name .
}"

The output shows the physical operators, index lookups, and estimated cardinalities that the query planner has chosen.

#Branch-aware queries

By default, queries run against the HEAD commit of the main branch. To query a different branch:

Branch names such as main, staging, or experiment are the normal user-facing selectors. Canonical BranchId values are opaque UUID URNs returned in response metadata and accepted anywhere a branch ref is allowed.

#CLI flag

wwkg client query "SELECT * WHERE { ?s ?p ?o }" --branch experiment

#In-query pragma

# wwkg-branch: experiment
SELECT * WHERE { ?s ?p ?o }

#HTTP header

POST /sparql
X-WWKG-Branch: experiment
Content-Type: application/sparql-query

SELECT * WHERE { ?s ?p ?o }

#URL parameter

POST /sparql?branch=experiment

When multiple channels specify a branch, the outermost wins: Header > URL parameter > body parameter > in-query pragma.

#Default-graph reading mode

WWKG follows strict SPARQL 1.1 default-graph semantics by default. The default graph is one specific graph (the reserved IRI urn:wwkg:graph:default). Writes that don’t name a graph land in it; reads that don’t name a graph see only its quads.

This matches what every standards-conformant SPARQL endpoint does out of the box. Most queries Just Work — but if your workspace is dominated by named graphs (e.g. every file you upload with wwkg upload lands in its own named graph), a naive query like:

SELECT ?s ?p ?o WHERE { ?s ?p ?o }

returns zero rows — the workspace has no quads in the positional default graph, only in the named graphs.

#Why is my SELECT * empty?

This is the most common surprise. Two fixes:

Add a GRAPH ?g wrapper when you mean “any graph”:

SELECT ?s ?p ?o WHERE { GRAPH ?g { ?s ?p ?o } }

Or flip the query to union mode with a comment directive:

# wwkg-default-graph: union
SELECT ?s ?p ?o WHERE { ?s ?p ?o }

The union mode makes bare BGPs match across the default graph and every named graph — the behaviour most other KG projects ship as an opt-in toggle (Stardog’s query.all.graphs=true, Jena’s tdb:unionDefaultGraph, Virtuoso’s DEFINE input:default-graph-uri, etc.).

#Forcing strict mode

The standards-conformant way to read only the positional default graph is a FROM clause naming the default graph IRI:

SELECT ?s ?p ?o
FROM <urn:wwkg:graph:default>
WHERE { ?s ?p ?o }

FROM overrides any pragma or workspace-level mode setting.

#SPARQL extensions

WWKG extends standard SPARQL with three graph patterns for version-aware queries.

#BRANCH — cross-branch queries

Query the same pattern across multiple branches:

SELECT ?branch ?name WHERE {
  VALUES ?branch {
    <urn:wwkg:branch:660e8400-e29b-41d4-a716-446655440000>
    <urn:wwkg:branch:660e8400-e29b-41d4-a716-446655440002>
  }
  BRANCH ?branch {
    <http://example.org/Alice> <http://example.org/name> ?name .
  }
}

#DELTA — what changed between versions

See which triples were inserted or deleted between two points in history:

SELECT ?op ?s ?p ?o WHERE {
  DELTA FROM "main~5" TO "main" {
    ?op ?s ?p ?o .
  }
}

The ~N suffix means “N commits before HEAD” (git-style). ?op binds to wwkg:Insert or wwkg:Delete.

#HISTORY — commit log

Query the commit history of a branch:

SELECT ?commit ?timestamp ?author ?message WHERE {
  HISTORY "main" {
    ?commit wwkg:timestamp ?timestamp ;
            wwkg:author ?author ;
            wwkg:message ?message .
  }
}
ORDER BY DESC(?timestamp) LIMIT 20

#SPARQL updates

Insert and delete triples using standard SPARQL Update syntax:

wwkg client update "INSERT DATA {
  <http://example.org/Alice> <http://example.org/age> 31 .
}"

wwkg client update "DELETE DATA {
  <http://example.org/Alice> <http://example.org/age> 30 .
}"