---
updatedAt: 2025-12-22T12:59:19.000Z
agentTools:
  projectIndex: https://changelog-dzt-kg.readme.io/llms.txt
---

# Shape Query API

## Introduction

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

```json Shape Query Example
{
  "@context": {
    "sq": "http://www.onlim.com/shapequery/",
    "@vocab": "http://www.onlim.com/shapequery/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "ds": "https://vocab.sti2.at/ds/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "schema": "https://schema.org/",
    "sh": "http://www.w3.org/ns/shacl#",
    "odta": "https://odta.io/voc/"
  },
  "sq:query": [
    {
      "@type": "schema:Event",
      "schema:location": {
        "schema:address": {
          "schema:addressLocality": "München"
        }
      },
      "schema:startDate": {
        "sq:value": "2025-01-01",
        "sq:op": ">=",
        "sq:datatype":"date"
      },
      "schema:endDate": {
        "sq:order": "asc"
      }
    }
  ]
}
```

A shape query definition is a JSON-LD document that consists 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

Language filtering...

Allows for the definition of the language of the value used for the comparison. For example, an element has a German (de) and an English (en) name. With `“sq:lang": "de"` you can specify that the German name should be used for the comparison.

* **sq:lang**: *String* - the desired language