GraphQL Tutorial
GraphQL and RDF

GraphQL queries and schemas
have no global semantics or identifiers

Querying over multiple GraphQL interfaces is hard with the current solutions:

• Schema delegation

  Stitch multiple schemas together, forward subqueries to other interfaces

• Schema federation

  Like delegation, with improved spreading of types over different interfaces

RDF offers solutions for this problem

Support for federation is built into its foundations.

• IRIs are unique identifiers of resources

  Instead of interface-specific IDs.

• Vocabularies have global semantics

  Instead of interface-specific schemas.

GraphQL can simplify access to RDF

GraphQL is highly popular and widely used.

• Many developers already known GraphQL

• A lot of tooling exists for GraphQL

→ Querying RDF with GraphQL would be highly beneficial.

Bridges between GraphQL and RDF exist

• HyperGraphQL

  GraphQL interface wrapper around RDF sources

• TopBraid

  Graph store with GraphQL interface via (SHACL) shape definitions

• Stardog

  SPARQL engine, with conversion of GraphQL to SPARQL

• GraphQL-LD

  Engine-independent GraphQL to SPARQL converter with JSON-LD contexts

HyperGraphQL exposes RDF sources
as a GraphQL interface

• Open-source
• Developed by Semantic Integration
• Server config defines RDF sources
• Server uses annotated GraphQL schema with links to sources
• Responses are enhanced with JSON-LD context

Configure a HyperGraphQL instance

config.json: interface parameters and available services (SPARQL, RDF files,...)

{
    "name": "dbpedia-sparql-hgql-demo",
    "schema": "schema.graphql",
    "server": {
        "port": 8080,
        "graphql": "/graphql",
        "graphiql": "/graphiql"
    },
    "services": [{
        "id": "dbpedia-sparql",
        "type": "SPARQLEndpointService",
        "url": "http://dbpedia.org/sparql/",
        "graph": "http://dbpedia.org"
    }]
}

Create an annotated GraphQL schema

__Context maps fields to IRIs
@service defines source for a type/field

type __Context {
  Person: _@href(iri: "http://dbpedia.org/ontology/Person")
  City:   _@href(iri: "http://dbpedia.org/ontology/City")
  name:   _@href(iri: "http://xmlns.com/foaf/0.1/name")
  label:  _@href(iri: "http://www.w3.org/2000/01/rdf-schema#label")
}

type Person @service(id:"dbpedia-sparql") {
  name: String @service(id:"dbpedia-sparql")
  label: [String] @service(id:"dbpedia-sparql")
  birthPlace: City @service(id:"dbpedia-sparql")
  birthDate: String @service(id:"dbpedia-sparql")
}

HyperGraphQL returns JSON-LD

Both valid GraphQL response and RDF

{
  "data": {
    "Person_GET": [
      {
        "_id": "http://dbpedia.org/resource/Sani_ol_molk",
        "_type": "http://dbpedia.org/ontology/Person",
        "name": "Mirza Abolhassan Khan Ghaffari"
      }
    ],
    "@context": {
      "_id": "@id",
      "_type": "@type",
      "name": "http://xmlns.com/foaf/0.1/name"
    }
  }
}

TopBraid enables GraphQL interaction

• Commercial product (slides based on public documentation)
• Developed by TopQuadrant
• Querying and updating RDF graphs with GraphQL queries
• GraphQL schemas are based on SHACL
• More: schema mapping to RDFS/SHACL, SHACL-based inference, GraphQL directives for defining shapes, ...

GraphQL querying of RDF with TopBraid

• SHACL shape definitions (or GraphQL schemas) → enhanced GraphQL schema
• Enhanced GraphQL schemas offer convenience functionality:
  
  
  • Filtering: by text or SPARQL expressions
  • Aggregations: count, sum, concat, ...
  • Ordering and Paging
  • Transformations: SPARQL functions
  • Introspection: available fields and types

Enhanced GraphQL schema in TopBraid

schema {
  query: RootRDFQuery
}

type RootRDFQuery {
  humans (...): [Human]
}

type Human {
  uri: ID!
  label: String!
  id (...): ID!
  name (...): String!
  friends (...): [Human]
}

...: auto-generated filters, aggregators, ...

GraphQL query in TopBraid

Enhanced GraphQL functionality: filtering, ordering, transformation

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

Stardog databases allow querying
using GraphQL queries

• Commercial product (slides based on public documentation)
• Developed by Stardog Union
• Converts GraphQL queries to SPARQL
• Optional GraphQL schema (@schema query var)
• Supports most SPARQL features (directives: filter, optional, bind, ...)

Conversion with default namespaces

{
  Human {
    name
    height
  }
}

SELECT ?name ?height WHERE {
  _:b1 a :Human;
       :name ?name;
       :height ?height.
}

Custom prefixes or aliases can be defined

query withPrefixes @prefix(foaf: "http://xmlns.com/foaf/0.1/") {
  Human {
    foaf:name
  }
}

query withAliases @config(alias: {myType: "http://ex.com/my-type",
                                  myProp: "http://ex.com/my-prop"}) {
  myType {
    myProp
  }
}

GraphQL-LD converts GraphQL to SPARQL

• Open-source engine-independent approach
• Developed IDLab
• Focus on GraphQL query, not schema
  → no GraphQL interface
• Converts GraphQL queries to SPARQL using JSON-LD context
• Converts SPARQL results to JSON tree

JSON-LD contexts are exploited

• GraphQL field to IRI with @id
• Reverse node relationships with @reverse
• Set literal language with @language
• Set literal datatype with @type
• → Contexts apply to both GraphQL query and JSON results

Conversion expands fields to IRIs

{
  label
  artist { label }
}

{
  "label": "http://www.w3.org/2000/01/rdf-schema#label",
  "artist": "http://dbpedia.org/ontology/musicalArtist"
}

SELECT ?label ?writer ?artist_label
WHERE {
  _:b1 rdfs:label ?label;
       dbo:writer ?writer.
  _:b1 dbo:musicalArtist [
    rdfs:label ?artist_label
  ].
}

Querying RDF with GraphQL: Overview

In Summary

• Federation with GraphQL is hard

  Because queries and schemas have no global semantics

• RDF and SPARQL offer solutions

  Federated querying is a well-established domain in the Semantic Web

• Crossing the bridge between GraphQL and RDF

  Multiple approaches exist: HyperGraphQL, TopBraid, Stardog, GraphQL-LD

• Bridges are incompatible

  Future standardization may be required for aligning approaches

Sources

• HyperGraphQL documentation: https://www.hypergraphql.org/documentation/
• TopQuadrant GraphQL: https://www.topquadrant.com/technology/graphql/
• Stardog Documentation: https://www.stardog.com/docs/#_graphql_queries
• GraphQL-LD Article: https://comunica.github.io/Article-ISWC2018-Demo-GraphQlLD/