Linked Data Querying with GraphQL
npm install 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:
``sparql`
SELECT ?id ?starring WHERE {
OPTIONAL {
?id
?starring
}
}
This could be written in a more compact way in GraphQL:
`graphql`
{
id
... on Film {
starring(label: "Brad Pitt")
}
}
And this can be based on the following JSON-LD context:
`json`
{
"@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"
}
}
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.
`bash`
$ yarn add graphql-ld
This package also works out-of-the-box in browsers via tools such as webpack and browserify.
`javascript`
import {Client} from "graphql-ld";
_or_
`javascript`
var Client = require("graphql-ld").Client;
_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._
`javascript
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 });
`
_This requires you to install graphql-ld-sparqlendpoint: yarn add graphql-ld-sparqlendpoint._
`javascript
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 });
`
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.
Query:
`graphql`
query @single {
label
}
Context:
`json`
{
"@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",
...
]
}
}
Query:
`graphql`
{
id @single
... on Film {
starring(label: "Brad Pitt") @single
}
}
Context:
`json`
{
"@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"
},
...
]
}
Query:
`graphql`
{
softwareName: label @single
developer @single(scope: all) {
label
country(label_en: "Belgium")
}
}
Context:
`json`
{
"@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"
}
},
...
]
}
This code is released under the MIT license.