Querying RDF Graphs with GraphQL

COUNT

Each multi-valued field is accompanied by a field named xyz_COUNT, producing an Int result for the number of values. COUNT fields can take the same filter arguments as the other fields, making it possible to count only certain values.

The following query returns the number of humans that have at least 4 friends:

Example GraphQL Query

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

CONCAT

Each multi-valued field is accompanied by a field named xyz_CONCAT, producing a String result by concatenating all matching values of the field. An empty string is delivered if there are no matching values. _CONCAT fields take an optional argument separator if the string should use something else than the default ", " between sub-strings.

The following query returns, for each human, the name and a single string consisting of all friends starting with L, separated by " and ":

Example GraphQL Query

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

An example response is:

Example GraphQL Query

{
	"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"
			}
		]
	}
}

The _CONCAT fields also support the orderBy arguments.

If the concatenated values are objects, then each object will be represented by its label by default. To construct strings from other values, use _CONCAT with the argument labelExpr which takes a SPARQL expression string as its value. In this expression you can access the same pre-bound variables as for filter expressions.

The following query would return a concatenation of the lower-case names of all friends.

Example GraphQL Query

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

The labelExpr argument can also be used for scalar fields, in which case the variable with the name of the underlying field is holding the literal value.

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.

orderBy, orderByDesc and orderByExpr

{
	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:

Example RDF/SHACL

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. 

Working with Reification

This feature requires TopBraid 6.4 onwards.

Properties that have been reified using dash:reifiableBy will have an additional GraphQL field consisting of the property field name and “Reif”. For example, you can query the time stamp of each value of the parent property for a person using:

Example GraphQL Query

{
    persons {
        parent(orderBy: label) { label }
        parentReif(orderBy: label) { timeStamp }
    }
}

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.

Example GraphQL Query

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

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:

Example GraphQL Query

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

Producing for example:

Example JSON result

}
	"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.

Example GraphQL Query

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

Producing for example:

Example JSON result

{
	"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:

Example GraphQL Query

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

Here is the shape introspection schema:

Example GraphQL 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.