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.

{
  "@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": "Zwiesel"
        }
      },
      "schema:startDate": {
        "sq:value": "2024-07-01",
        "sq:op": ">=",
        "sq:datatype":"date"
      },
      "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