Skip to main content

Querying with SPARQL

SPARQL is to a graph what SQL is to tables. If you can write a SELECT with joins, you can write SPARQL — the shape is SELECT ?vars WHERE { pattern } where the pattern is a set of subject–predicate–object triples that share variables.

Where to Run Queries

Ontology-scoped SPARQL reads one version of that ontology: the active release by default, or the working draft (scope=draft) for users with edit permission. It works with RDF storage off and cannot reach other assets or external datasets. Catalog-wide SPARQL in the Playground runs against the triple store and is admin-only. The MCP tool is the exception. Non-administrators who hold ExecuteSparqlQuery can run it through a restricted profile. The profile allows only SELECT queries with JSON output and no inference. It rejects FROM, GRAPH, SERVICE, and CALL, and it bounds result size and runtime. For more information, see AI Agents.

Named Graphs

Always scope instance-data queries to the knowledge graph. Ontology and shapes triples live elsewhere, so an unscoped ?s ?p ?o returns schema noise.

Prefixes

The console pre-populates these; include them in API calls yourself.

The Vocabulary You Will Use Most

Entity IRIs follow https://open-metadata.org/entity/{entityType}/{uuid}.
Discover the schema instead of guessing it. GET /api/v1/rdf/ontology returns the full ontology; the MCP tool ontology_describe does the same for agents and accepts a resource URI for a focused DESCRIBE. Reading the actual class and property declarations beats guessing predicate names — for you and for an LLM.

Limits

Every read runs behind an admission guard: Writes (INSERT, DELETE, DROP, LOAD, CLEAR, CREATE) are rejected on the read endpoints. POST /api/v1/rdf/sparql/update exists for admins, but see the warning below. Federation (SERVICE clauses to external endpoints) is disabled by default. When federation is enabled, target URIs must appear verbatim in an allowlist, and trailing slashes matter. A SERVICE clause hidden inside EXISTS is refused too. Ontology-scoped queries run in an isolated process with their own memory limit. If an ontology is too large to load, the query fails with an error that says so.
Do not use SPARQL UPDATE to change your catalog. The graph is a derived index; the next reindex discards anything written directly. Write through the entity APIs.

Cookbook

Discovery

Governance

Lineage

prov:wasDerivedFrom+ is a property path — SPARQL’s transitive traversal operator. It is the single feature that makes graph queries worth the switch, and it has no clean SQL equivalent. If you enable the transitive lineage closure inference rule, the closure is materialized and you can drop the +.

The Ontology, Applied

Structure

Calling the API

Result formats: json (default), xml, csv, tsv for SELECT/ASK; turtle, jsonld, ntriples, rdfxml for CONSTRUCT/DESCRIBE.

RDF 1.2 Support

SPARQL queries can use RDF 1.2 features. Both the admin endpoint and the MCP sparql_query tool accept them. Non-administrators keep the restricted profile: SELECT queries with JSON output, and no GRAPH clause.
  • SPARQL 1.2 syntax: VERSION "1.2", the TRIPLE() and LANGDIR() functions, and <<( s p o )>> triple-term patterns.
  • Triple terms: a triple term can bind to a result variable, including rdf:reifies statements and blank nodes nested inside a triple.
  • Directional literals: language-tagged strings with a base direction, such as "قطة"@ar--rtl.

Results in JSON

JSON results follow the SPARQL 1.2 Query Results JSON format:
  • A triple binding has type set to triple. Its value is an object with recursive subject, predicate, and object terms, instead of a string.
  • A directional literal carries an its:dir field set to ltr or rtl, next to xml:lang.
  • Existing bindings for IRIs, literals, and blank nodes are unchanged.
If you call the MCP sparql_query tool or the generated SDK clients, the value of a result term can now be an object, not only a string. Update any code that assumes it is always a string.
The SPARQL Playground renders a triple term as <<( <subject> <predicate> "قطة"@ar--rtl )>>. SPARQL console running an RDF 1.2 query, with the triple term shown in the result
OpenMetadata writes the graph for its own entities as RDF 1.1. RDF 1.2 terms enter through imported ontologies and the queries you write. OpenMetadata carries them through storage, query, and results unchanged.

Serialization Formats

Do not round-trip RDF 1.2 text through JSON-LD. Directional literals are written with the JSON-LD 1.1 i18n datatype, which does not read back as rdf:dirLangString.

Performance Notes

  • Always scope to the named graph. Unscoped patterns scan schema and shapes as well.
  • LIMIT early. The guard truncates you at 1,000 rows by default anyway; be explicit.
  • Bind the most selective triple first. Start from a specific IRI or an indexed literal like om:fullyQualifiedName, not from ?s a om:Table.
  • Property paths are powerful and expensive. + and * over a large lineage graph can hit the 30-second timeout. If you run one regularly, materialize it as an inference rule instead.
  • Prefer FILTER NOT EXISTS over OPTIONAL + !BOUND. Same result, better plan.

Next

Reasoning & Validation

Materialize the closures you keep re-computing.

Graph Insights

Pre-computed importance, communities, and paths.