Querying RDF Graphs with GraphQL

This document describes the features of the TopBraid GraphQL services. TopBraid products automatically generate GraphQL schemas from existing SHACL shape definitions, as explained in Publishing RDF/SHACL Graphs as GraphQL. The generated GraphQL schemas include built-in facilities to filter data using direct value matching, complex query patterns and even SPARQL expressions. Furthermore, the schemas define aggregation, ordering and paging of results, as well as dynamically deriving values for the JSON response. Using the schemas, implementations can convert RDF graph data into JSON object structures (and back).

Introduction

TopBraid takes SHACL shape definitions or GraphQL schemas as input and generates an enhanced GraphQL schema that provide numerous features to query data stored in an RDF dataset. In this document we take the viewpoint of a typical GraphQL user, such as a UI developer or data analyst, to explain which features are available. Our starting point is a GraphQL schema:

type Human {
	id: ID!
	name: String!
	height: Float
	friends: [Human]
}

The processor will internally convert it to SHACL and then generate the following GraphQL schema:

schema {
	query: RootRDFQuery
}

type RootRDFQuery {
	humans (... filters etc, see later...): [Human]
	... generated fields for aggregations and introspection ...
}

type Human {
	uri: ID!
	label: String!
	id (... filters etc...): ID!
	name (... filters etc...): String!
	height (... filters etc...): Float
	friends (... filters etc...): [Human]
	... generated fields for aggregations, derived values ...
}

As shown above, the system automatically produces a root query object that has fields for every public shape, with a name that is basically the plural form of the shape name. These root query fields can take a large number of arguments to select which of the matching objects shall be returned, but we get to that later.

Each object type has a field uri storing the URI of the underlying RDF resource and label to query a human-readable display label.

Completing this introductory example, here is an example GraphQL query against this schema, returning all humans where the name starts with L, and all their friends, translating the height from meters to feet.

{
	humans (where: {name:{pattern:"^L"}}, orderBy: name) {
		id
    	name
		height (transform: "$height / 0.3048")
		friends {
			id
			name
		}
	}
}

A possible result JSON would be:

{
	"data": {
		"humans": [
			{
				"id": "1003",
				"name": "Leia Organa",
				"height": 4.921259842519685,
				"friends": [
					{
						"id": "1002",
						"name": "Han Solo"
					},
					{
						"id": "1000",
						"name": "Luke Skywalker"
					}
				]
			},
			...
		]
	}
}

Filtering

Most fields that are generated by the engine can take arguments to filter out which values to return. The various kinds of filters are described in the next sub-sections.

{
	humans(appearsIn: "JEDI") {
    	name
	}
}

{
	humans(where: {
			starships: {
				exists: {
					length: {
						minInclusive: 30
					}
				}
			}
		}) {
		name
		height
		homePlanet
		starships {
			name
			length
		}
	}
}

{
	humans (queryText: "^l") {
		name
	}
}

{
	humans (filter: "$height > 1.6") {
		name
	}
}

Aggregations

As of TopBraid 6.1 this feature is deactivated by default (to reduce the complexity of the generated GraphQL schema). If needed, enable it using the Server Configuration Parameters page, or use Property Value Rules to expose selected kinds of aggregations.

Most database query languages support some form of aggregations, typically including COUNT, SUM, MIN, MAX, AVG and MEDIAN. Another form of aggregations is to build strings by concatenating multiple values. In this GraphQL implementation, only COUNT and CONCAT are supported for now. (Future versions may support SUM, MIN, MAX, AVG and MEDIAN if there is demand - let us know). Aggregation fields are available for multi-valued fields only.

{
	humans_COUNT (where: {friends: {minCount: 4}})
}

{
	humans {
		label
		friends_CONCAT(where:{name:{pattern:"^L"}}, separator: " and ", orderBy: label)
	}
}

{
	"data": {
		"humans": [
			{
				"label": "Character-1000",
				"friends_CONCAT": "Character-1003"
			},
			{
				"label": "Character-1002",
				"friends_CONCAT": "Character-1000 and Character-1003"
			},
			{
				"label": "Character-1003",
				"friends_CONCAT": "Character-1000"
			}
		]
	}
}

{
	humans {
		label
		friends_CONCAT (labelExpr: "LCASE($name)", orderBy: name)
	}
}

Ordering and Paging

By default, RDF triples are unsorted. This section explains how a certain order can be accomplished, and how to page through large numbers of items.

{
	humans (orderBy: height, orderByDesc: true) {
		name
		height
	}
}

{
	humans(orderBy: name, first: 10, skip: 20) {
		name
		height
	}
}

Working with rdf:Lists

This feature requires TopBraid 6.2 onwards.

By default, rdf:Lists are treated like any other RDF value, and the recursive structure of list nodes has no special support by GraphQL. If you want rdf:Lists to be handled like JSON arrays (multi-valued GraphQL fields) then you need to make sure that TopBraid can understand the intention and knows what type the list member have. The supported design pattern is described in this blog post. In particular, the sh:node of your property shape needs to be dash:ListShape:

ex:PlayList
    a sh:NodeShape, rdfs:Class ;
    sh:property [
        sh:path ex:songs ;
        sh:maxCount 1 ;
        sh:node dash:ListShape ;
        sh:property [
            sh:path ( [ sh:zeroOrMorePath rdf:rest ] rdf:first ) ;
            sh:class ex:Song ;
        ]
    ] .

Note that the sh:maxCount 1 is recommended to clarify that there can only be one list per subject. Cases with multiple rdf:Lists are not supported.

Transformations

Each field with a scalar value type can take an argument transform that takes a SPARQL expression string as its value. If a transform is present, the values delivered for the field are passed into the expression (as a variable with the same name as the field), and the result of the evaluation will be returned instead of the original value. In these expressions, the values of any other single-valued field can also be accessed as named variables, as can $label and $uri, as well as $this to access the surrounding resource.

In the following example, the height of each human is converted from meters to feet, and the name is returned in all upper-case letters.

{
	humans {
		name (transform: "UCASE($name)")
		height (transform: "$height * 3.28084")
	}
}

Derived Fields

As of TopBraid 6.1 this feature is deactivated by default (to reduce the complexity of the generated GraphQL schema and make it more difficult to write inefficient queries). If needed, enable it using the Server Configuration Parameters page, or use Property Value Rules to define the kinds of inferences that are supported for a schema.

While transformations can modify how existing values are returned, it is sometimes useful to compute arbitrary field values dynamically. Each object type has the following generated fields in addition to the declared fields: deriveBoolean, deriveFloat, deriveInt and deriveString. The value types of these are single values of the corresponding scalar types. They take a single required argument expr of type String that must be a valid SPARQL expression. In these expressions, the values of other properties of the underlying RDF resource can be queried as pre-bound variables. Furthermore, the variables $this, $label and $uri are pre-bound. The result of the expression will be returned in the specified scalar type.

It is common to use GraphQL aliases so that the names in the generated JSON will not start with "derive". The following example delivers the length of each human's name as a separate integer field:

{
	humans {
		name
		nameLength: deriveInt(expr: "STRLEN($name)")
	}
}

Producing for example:

{
	"data": {
		"humans": [
			{
				"name": "Luke Skywalker",
				"nameLength": 14
			},
			{
				"name": "Han Solo",
				"nameLength": 8
			},
			{
				"name": "Leia Organa",
				"nameLength": 11
			}
		]
	}
}

In addition to these single-valued deriveXY fields, there is also the special field deriveStrings that can be used to generate a list of String values. This takes a single required argument query that must be a SPARQL SELECT query producing a single result variable. The query will be executed with the variable $this pre-bound to the current context resource.

{
	humans {
		name
		friendNames: deriveStrings (query: "SELECT ?name { $this starwars:friends/starwars:name ?name } ORDER BY ?name")
	}
}

Producing for example:

{
	"data": {
    	"humans": [
			{
				"name": "Luke Skywalker",
				"friendNames": [
					"C-3PO",
					"Han Solo",
					"Leia Organa",
					"R2-D2"
				]
			},
			...
		]
	}
}

Note that the June 2018 version of the GraphQL spec introduces multi-line strings using the """ syntax, making complex SPARQL queries more readable.

Introspection

Any standards-compliant GraphQL implementation supports some built-in introspection query types that provide information about the available object and field types. However, these generic capabilities would not return the details of the richer RDF/SHACL model underneath, and would also include information about the various automatically generated objects and fields that are often not of interest to introspecting clients. The alternative introspection query types from this section are available to provide a view on the underlying SHACL structure.

The following example illustrates a typical use case, returning information that may be used to populate an input form for objects matching a given type:

{
	_typeShapeByName(name: "Human") {
		groups {
			label
			fields {
				label
			}
		}
	}
}

Here is the shape introspection schema:

type RootRDFQuery {
	...
	_typeShapeByName(name: String!): _TypeShape
	_typeShapeByURI(uri: String!): _TypeShape
	_typeShapesForResource(uri: String!): [_TypeShape]
}

# Metadata about a type as derived from its shape(s).
type _TypeShape {
	uri: String!
	name: String!
	label: String!
	rootQueryField: String
	fields: [_FieldShape]
	fieldByName (name: String!): _FieldShape
	groups: [_FieldGroup]
}

# Metadata about a field group.
type _FieldGroup {
	uri: String!
	label: String!
	order: Float!
	fields: [_FieldShape]
}

# Metadata about a field as derived from its shape(s).
type _FieldShape {
	name: String!
	label: String!
	datatype: _Resource
	externalType: _Resource
	typeShape: _TypeShape
	scalar: Boolean!
	unionTypeNames: [String]
	minCount: Int!
	maxCount: Int
	min: String
	max: String
	isMinExclusive: Boolean!
	isMaxExclusive: Boolean!
	minLength: Int!
	maxLength: Int
	pattern: String
	group: _FieldGroup
	order: Float!
}

This information can be combined with follow-up queries using the standard introspection schema, for example to find the enumerated values of an enum.

Note that the special cases of xsd:string or rdf:langString and its inverse variation rdf:langString or xsd:string (using sh:or) are mapped to rdfs:Literal in the _FieldShape.datatype field.