README.md

GraphQL-LD

GraphQL-LD allows Linked Data to be queried via GraphQL queries and a JSON-LD context.

It is a developer-friendly way to query Linked Data and use the results in a straightforward way.

For example, 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"
  }
}

Approach

This library takes a GraphQL-LD query and a JSON-LD context as input, converts it to a SPARQL query, sends the SPARQL query to a SPARQL query engine for execution (local or endpoint), and converts the SPARQL query results into a tree-based structure corresponding to the original GraphQL query.

More information about this approach can be found in our GraphQL-LD article.

Install

$ yarn add graphql-ld

This package also works out-of-the-box in browsers via tools such as webpack and browserify.

Require

import {Client} from "graphql-ld";

or

var Client = require("graphql-ld").Client;

Usage

With a client-side query engine

This requires you to install graphql-ld-comunica: yarn add graphql-ld-comunica.

If you want to use this for Solid apps, have a look at graphql-ld-comunica-solid instead.

import {Client} from "graphql-ld";
import {QueryEngineComunica} from "graphql-ld-comunica";

// Define a JSON-LD context
const context = {
  "@context": {
    "label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label" }
  }
};

// Create a GraphQL-LD client based on a client-side Comunica engine over 2 sources
const comunicaConfig = {
  sources: [ "http://dbpedia.org/sparql", "https://ruben.verborgh.org/profile/" ],
};
const client = new Client({ context, queryEngine: new QueryEngineComunica(comunicaConfig) });

// Define a query
const query = `
  query @single {
    label
  }`;

// Execute the query
const { data } = await client.query({ query });

With a remote SPARQL endpoint

This requires you to install graphql-ld-sparqlendpoint: yarn add graphql-ld-sparqlendpoint.

import {Client} from "graphql-ld";
import {QueryEngineSparqlEndpoint} from "graphql-ld-sparqlendpoint";

// Define a JSON-LD context
const context = {
  "@context": {
    "label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label" }
  }
};

// Create a GraphQL-LD client based on a SPARQL endpoint
const endpoint = 'http://dbpedia.org/sparql';
const client = new Client({ context, queryEngine: new QueryEngineSparqlEndpoint(endpoint) });

// Define a query
const query = `
  query @single {
    label
  }`;

// Execute the query
const { data } = await client.query({ query });

Examples

Below, you can find a couple examples of GraphQL-LD queries.

If you want more details on what kind of queries you can write, have a look at the README of the GraphQL-to-SPARQL repository.

Finding all available labels

Query:

query @single {
  label
}

Context:

{
  "@context": {
    "label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label" }
  }
}

Output:

{
  "data": {
    "label": [
      "amateur victory",
      "amateur year",
      "ambasadóir",
      "ambasciatore",
      "ambassadeur",
      "ambassadeur",
      "ambassador",
      ...
    ]
  }
}

Finding all movies Brad Pitt stars in

Query:

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

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

Output:

{
  "data": [
    {
      "id": "http://dbpedia.org/resource/Ocean's_Eleven",
      "starring": "http://dbpedia.org/resource/Brad_Pitt"
    },
    {
      "id": "http://dbpedia.org/resource/The_Favor",
      "starring": "http://dbpedia.org/resource/Brad_Pitt"
    },
    {
      "id": "http://dbpedia.org/resource/The_Assassination_of_Jesse_James_by_the_Coward_Robert_Ford",
      "starring": "http://dbpedia.org/resource/Brad_Pitt"
    },
    {
      "id": "http://dbpedia.org/resource/True_Romance",
      "starring": "http://dbpedia.org/resource/Brad_Pitt"
    },
    ...
  ]
}

Finding all Belgian software developers

Query:

{
  softwareName: label @single
  developer @single(scope: all) {
    label
    country(label_en: "Belgium")
  }
}

Context:

{
  "@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" },
    "developer": { "@id": "http://dbpedia.org/ontology/developer" },
    "country": { "@id": "http://dbpedia.org/ontology/locationCountry" }
  }
}

Output:

{
  "data": [
    {
      "softwareName": "Divinity: Original Sin II",
      "developer": {
        "label": "Larian Studios",
        "country": "http://dbpedia.org/resource/Belgium"
      }
    },
    {
      "softwareName": "Divinity: Original Sin II",
      "developer": {
        "label": "Larian Studios",
        "country": "http://dbpedia.org/resource/Belgium"
      }
    },
    {
      "softwareName": "BioNumerics",
      "developer": {
        "label": "Applied Maths",
        "country": "http://dbpedia.org/resource/Belgium"
      }
    },
    ...
  ]
}

License

This software is written by Ruben Taelman.

This code is released under the MIT license.