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":"Eisenach"
				}
			},
			"schema:startDate":{
				"sq:value":"2021-12-17",
				"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 which is used to find things that match that graph pattern in the data. This allows the user to define properties and property path (nested properties) that need to exists or where the value has to fit a certain condition.
If there is more than one query object we perform a 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 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 definition at the same level are treated as an and condition.

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