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-ldThis 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.
![renovate[bot]](https://avatars.githubusercontent.com/u/29139614?size=120)
![greenkeeper[bot]](https://avatars.githubusercontent.com/u/23040076?size=120)