GraphQL-LD

On this page

Instead of SPARQL queries, you can also provide GraphQL-LD queries, which are GraphQL queries enhanced with a JSON-LD context. GraphQL-LD is a developer-friendly alternative to SPARQL that allows querying Linked Data and using the results in a straightforward way.

What is GraphQL-LD?

Assuming the following SPARQL query:

SELECT ?id ?starring WHERE {
  OPTIONAL {
    ?id <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/ontology/Film>;
      <http://dbpedia.org/ontology/starring> ?starring.
    ?starring <http://www.w3.org/2000/01/rdf-schema#label> "Brad Pitt"@en.
  }
}

This could be written in a more compact way in GraphQL:

{
  id
  ... on Film {
    starring(label: "Brad Pitt")
  }
}

And this can be based on the following JSON-LD context:

{
  "@context": {
    "Film": "http://dbpedia.org/ontology/Film",
    "label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
    "starring": "http://dbpedia.org/ontology/starring"
  }
}

Learn more about the features of GraphQL-LD on GitHub, or read an article about GraphQL-LD.

Using GraphQL-LD on the command line

To run GraphQL queries with Comunica SPARQL from the command line, set the -i flag to graphql and refer to your config file with the JSON-LD context (@context) through the -c flag. To output your results as a GraphQL tree, set the MIME type of the output with -t to tree.

For example, the first 100 labels in DBpedia can be retrieved as follows:

$ comunica-sparql http://fragments.dbpedia.org/2015-10/en \
  -q "{ label(first: 100) @single }" \
  -c "{ \"@context\": { \"label\" : \"http://www.w3.org/2000/01/rdf-schema#label\" } }" \
  -i graphql \
  -t tree

Since the queries and contexts can be inconvenient to pass on the command line, they can also be supplied as files:

$ comunica-sparql http://fragments.dbpedia.org/2015-10/en \
  -f query.graphql \
  -c config-with-context.json \
  -i graphql \
  -t tree

Using GraphQL-LD in an application

If you want to execute GraphQL-LD queries in your application, you can do this as follows:

const QueryEngine = require('@comunica/query-sparql').QueryEngine;
const bindingsStreamToGraphQl = require('@comunica/actor-query-result-serialize-tree').bindingsStreamToGraphQl;

const myEngine = new QueryEngine();
const result = await myEngine.query(`
{
  label @single
  writer(label_en: \"Michael Jackson\") @single
  artist @single {
    label @single
  }
}
`, {
  sources: ['http://fragments.dbpedia.org/2016-04/en'],
  queryFormat: {
    language: 'graphql',
    version: '1.0'
  },
  "@context": {
    "label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label" },
    "label_en": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
    "writer": { "@id": "http://dbpedia.org/ontology/writer" },
    "artist": { "@id": "http://dbpedia.org/ontology/musicalArtist" }
  }
});
// Converts raw Comunica results to GraphQL objects
const data = await bindingsStreamToGraphQl(await result.execute(), result.context, {materializeRdfJsTerms: true});