Shape Query API


Shape Queries are a GraphQL inspired query language to define queries over the knowledge graph.
Below is an example of such a shape query.

  "@context": {
    "sq": "",
    "@vocab": "",
    "xsd": "",
    "ds": "",
    "rdf": "",
    "rdfs": "",
    "schema": "",
    "sh": "",
    "odta": ""
  "sq:query": [
      "@type": "schema:Event",
      "schema:location": {
        "schema:address": {
          "schema:addressLocality": "Zwiesel"
      "schema:startDate": {
        "sq:value": "2024-07-01",
        "sq:op": ">=",
      "schema:endDate": {
        "sq:order": "asc"

A shape query definition is a JSON-LD document, consisting of an optional but recommended, @context definition (to specify namespaces) and the actual query definitions in the sq:query property.

ShapeQueries provide a very flexible way to define one or more query filter groups (also referred to as query objects)

Define a ShapeQuery

A shape query definition can be seen as a graph query template used to find things that match that graph pattern in the data. This allows the user to define properties and property paths (nested properties) that need to exist or where the value has to fit a certain condition.
If there is more than one query object we perform an OR query(e.g. in case we need to define the search differently for different objects)

Below is a list of currently supported operators.

Filter operators

  • @type: string with an IRI or QName value
    Restrict the type
  • sq:value: string
    specify the filter value of a property
  • sq:op: string specify the filter condition
    the following operators are supported
    • contains - value contains the filter string
    • iContains - string contains ignore case
    • >, <, >= <= = - basic value comparison
  • sq:datatype: string define datatype of the filter value
    supported datatypes
    • date - xsd:date
    • dateTime - xsd:dateTime
    • iri - value is a IRI
    • int - convert to numerical value
  • sq:exists: boolean - specify that a certain property or property path must exist or not
  • sq:order string - specify that results should be ordered by that value in ascending or descending order
    supported values
    • asc - order by this value in ascending order
    • desc - order by this value in descending order
  • sq:lang : string - filter values by language
    supported value - 2-letter language acronym

Multiple properties filter definitions at the same level are treated as an and condition.

  • sq:or [] - one of the filter expressions needs to match
  • sq:and [] - all of the filter expressions need to match