Skip to main content

How to query the Knowledge Graph

The Knowledge Graph Manager (KGM) exposes two interfaces for exploring business knowledge: Search and SPARQL.

Both interfaces use the same request and response structure for internal and passthrough queries, so clients can switch between them by changing only the base path.

note

The examples in this section use the SKOS vocabulary (for instance skos:broader, skos:prefLabel, skos:definition) because it is a common and natural way to model business concepts.

However, KGM is not limited to SKOS: you may use any vocabulary expressed in RDF, including RDFS, OWL, or custom predicates.

Search — Discover Concepts by Text​

Search allows clients to find concepts using keywords. It is most useful when you know words related to a concept but not the exact identifier.

Search works by matching text against a configurable set of predicates.

info

The configurator defines which literal properties are indexed and searchable (for example: preferred labels, alternative labels, descriptions, definitions).

This configuration applies only to internal search. Passthrough search always reflects the upstream source's own search logic.

What Search Returns​

Search always returns full IRIs, for example:

  • https://example.com/concepts/Customer
  • https://data.myorg.com/glossary/OperationalRisk

Labels, descriptions, or definitions are not returned by the search endpoint.

Clients can retrieve those details afterward using SPARQL.

Suppose the configurator sets the following literal predicates for internal search:

  • rdfs:label
  • skos:altLabel

Then a search for "risk" would match concepts such as:

  • a concept whose primary label is "Liquidity Risk"
  • a concept with an alternative label "Operational risk"

If a predicate is not configured (for example, a custom "domain:notes" field), its content will not be searchable.

Passthrough search ignores this configuration entirely and behaves according to the upstream system's search semantics.

Example Search Request​

GET /v1/search/query?term=customer&limit=3

Example Search Response​

{
  "results": [
    "https://example.com/concepts/Customer",
    "https://example.com/concepts/CustomerOrder",
    "https://example.com/concepts/CustomerProfile"
  ],
  "totalResults": 42,
  "offset": 0,
  "limit": 3
}

Results are ordered by relevance.

  • Internal search runs over the ingested knowledge stored inside KGM.
  • Passthrough search forwards the request directly to a source that provides its own search API.

To use passthrough search, change only the base path:

GET /passthrough/{sourceId}/v1/search/query?term=customer

Request structure and response format remain identical.

If passthrough search is not enabled for a given source, KGM returns an error.

SPARQL — Explore Concepts and Relationships​

SPARQL is the standard RDF query language.

It allows you to retrieve concepts, navigate hierarchies, inspect metadata, and discover relationships.

SPARQL queries may use prefixes for readability, and responses use the W3C SPARQL Results JSON format.

tip

Learn more about:

Example: Retrieve Narrower Concepts of “Vehicle”​

PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?child ?label WHERE {
  ?child skos:broader <https://example.com/concepts/Vehicle> .
  OPTIONAL { ?child skos:prefLabel ?label }
}
ORDER BY ?label

Example Response​

{
  "head": { "vars": ["child", "label"] },
  "results": {
    "bindings": [
      {
        "child": { "type": "uri", "value": "https://example.com/concepts/Car" },
        "label": { "type": "literal", "value": "Car" }
      },
      {
        "child": {
          "type": "uri",
          "value": "https://example.com/concepts/Truck"
        },
        "label": { "type": "literal", "value": "Truck" }
      }
    ]
  }
}

Example: Retrieve the Definition of a Concept​

PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?definition WHERE {
  <https://example.com/concepts/LiquidityRisk> skos:definition ?definition .
}
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?related ?label WHERE {
  <https://example.com/concepts/Customer> skos:related ?related .
  OPTIONAL { ?related skos:prefLabel ?label }
}

Internal SPARQL vs. Passthrough SPARQL​

Internal SPARQL​

Internal SPARQL queries operate on the RDF graph composed of ingested knowledge only.

Use internal SPARQL when you want:

  • a unified conceptual graph across multiple sources
  • predictable navigation across broader, narrower, and related concepts
  • consistent metadata retrieval (labels, definitions, groupings)

Passthrough SPARQL​

If a source exposes a SPARQL endpoint, KGM provides a passthrough equivalent:

POST /passthrough/{sourceId}/v1/graph/sparql

Characteristics:

  • same SPARQL request format
  • same SPARQL JSON result format
  • only the base URL differs
  • the query is executed directly by the upstream source

Use passthrough SPARQL when:

  • the source supports richer SPARQL features
  • the source provides domain-specific relationships not ingested into KGM
  • you need real-time results directly from the authoritative system

If passthrough is disabled for a source, KGM returns an error.

SPARQL Capabilities and Limitations​

KGM supports a well-defined subset of SPARQL 1.1 to ensure predictable behavior across different types of knowledge sources.

Supported and Reliable​

  • PREFIX declarations
  • Basic graph patterns (?s ?p ?o)
  • Navigating explicit relationships defined in the RDF data
  • FILTER, OPTIONAL, ORDER BY, LIMIT, OFFSET
  • Retrieving literals (labels, definitions, descriptions, or any other literal properties)

Not Supported or Limited​

  • SPARQL Update (INSERT / DELETE)
  • Federated queries (SERVICE)
  • Complex or arbitrary-length property paths (for example using * or + operators)
  • Advanced or backend-dependent functions (certain date/time operations, complex numeric functions, or regex/internationalization-heavy string functions)
  • Deeply nested patterns or queries requiring full reasoning or inference (for example, OWL or RDFS entailment)

If a source requires more advanced SPARQL features, passthrough SPARQL may satisfy those needs when the upstream system provides richer capabilities.

Example workflow using Search and SPARQL​

Step 1 — Discover concepts​

GET /v1/search/query?term=compensation

Returns IRIs such as:

https://example.com/concepts/Compensation
https://example.com/concepts/BaseSalary
https://example.com/concepts/BonusPayout

Step 2 — Retrieve concept metadata using SPARQL​

PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?label ?definition WHERE {
  <https://example.com/concepts/BaseSalary> skos:prefLabel ?label .
  OPTIONAL { <https://example.com/concepts/BaseSalary> skos:definition ?definition }
}

Step 3 — Navigate the hierarchy​

PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?parent WHERE {
  <https://example.com/concepts/BaseSalary> skos:broader ?parent .
}

Step 4 — Use passthrough SPARQL for domain-specific relationships​

POST /passthrough/hr-ontology/v1/graph/sparql
PREFIX hr: <https://hr.example.com/ontology/>

SELECT ?component WHERE {
  <https://hr.example.com/concepts/CompensationPackage> hr:hasComponent ?component .
}

Passthrough allows access to additional semantics, richer domain structures, or concepts not ingested into the internal graph.