SPARQL reads and controlled updates

SPARQL is an advanced semantic interface distinct from a published YAML query. It can read the project's accessible bound dataset using SELECT, ASK, CONSTRUCT or DESCRIBE. Consumer SPARQL is disabled until an organization owner enables it. MCP exposes read-only SPARQL; HTTP has a separately controlled update path.

Read prerequisites

You need a Semogram account, project access, a compiled package and active bindings with actual records. Consumer SPARQL must be enabled and the caller needs sparql:query plus applicable read access. Use the operations model and bound Order/status records for this example. Denied and masked terms are excluded from the consumer dataset.

Run the read-only SELECT below over the selected project package, bounded execution, limit 10. Confirm Consumer SPARQL is enabled and show the actual package and query. Report source snapshots and limitations; do not enable access or perform updates implicitly.

PREFIX ex: <https://example.com/operations#>
SELECT ?order ?status
WHERE {
  ?order a ex:Order .
  OPTIONAL { ?order ex:status ?status }
}
LIMIT 10

curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_UUID>/ontology/sparql?ontologyPackageId=<COMPILED_PACKAGE_UUID>" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Content-Type: application/sparql-query" \
  --header "Accept: application/sparql-results+json" \
  --data-binary @- <<'SPARQL'
PREFIX ex: <https://example.com/operations#>
SELECT ?order ?status
WHERE {
  ?order a ex:Order .
  OPTIONAL { ?order ex:status ?status }
}
LIMIT 10
SPARQL

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sparql_query",
    "arguments": {
      "projectId": "<PROJECT_UUID>",
      "ontologyPackageId": "<COMPILED_PACKAGE_UUID>",
      "query": "PREFIX ex: <https://example.com/operations#>\nSELECT ?order ?status\nWHERE {\n  ?order a ex:Order .\n  OPTIONAL { ?order ex:status ?status }\n}\nLIMIT 10",
      "execution": "bounded"
    }
  }
}

Compare the returned order IDs and values with the real fixture. SPARQL Results JSON has its own structure; it is not the published query's data.rows envelope.

Bounded versus delegated

Bounded execution builds a policy-filtered project dataset under runtime fact limits. Delegated execution sends a safe read to a plugin endpoint with an Active Materialized binding for this package. It requires a real dataEndpointId and plugin SPARQL support; it is not available for every fact-store installation. Apache Jena is a plugin-backed option; inspect its installed capability and binding first.

HTTP uses execution=delegated&dataEndpointId=<UUID>; MCP uses those fields in arguments. Delegated execution is read-only. Backend-specific results and consistency do not automatically match a bounded federation. Explicitly request inference=rdfs-owl-relations-v1 only when that supported named-term profile is wanted.

Controlled HTTP updates

The HTTP endpoint accepts POST application/sparql-update when Consumer SPARQL mode is read/write and the caller has sparql:update. It requires an Idempotency-Key, checks semantic revision and records a write event. It is not delegated plugin update and is not exposed through MCP sparql_query.

An owner must deliberately enable the mode; a read request is not authorization to change it. Updates are governed semantic operations rather than a general escape hatch for arbitrary database writes. Use the dedicated source, mapping, materialization and assertion workflows where they express the intended change. Inspect the affected records and write event afterward.

Limits and formats

Requests are bounded to 1 MB. GET reads accept one query parameter; POST supports SPARQL text or supported form encoding. External default/named/using graph parameters are disabled: the endpoint supplies its project graph. Choose Accept appropriate to the read form. A bounded SPARQL result is not an unrestricted export of every inaccessible or unscanned record.