# graphql-ld > Linked Data Querying with GraphQL Latest version **2.0.0** (published 2025-01-09) · MIT license · 0 weekly downloads ## Install ```sh npm install graphql-ld pnpm add graphql-ld yarn add graphql-ld bun add graphql-ld ``` ## Health **Score 45/100 (D)** — status: stable. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 2.0.0 | | Published | 2025-01-09 | | First published | 2019-02-18 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 4 | | Unpacked size | 26.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 121 | | Author | Ruben Taelman | | Maintainers | rubensworks | | Keywords | graphql, graphqlld, sparql, query, rdf, linked data | ## Links - npm: https://www.npmjs.com/package/graphql-ld - Repository: https://github.com/rubensworks/graphql-ld.js - Homepage: https://github.com/rubensworks/graphql-ld.js#readme - Issues: https://github.com/rubensworks/graphql-ld.js/issues - Funding: https://github.com/sponsors/rubensworks/ - npm.io page: https://npm.io/package/graphql-ld ## Dependencies (4) - [sparqlalgebrajs](https://npm.io/package/sparqlalgebrajs.md) ^5.0.0 - [graphql-to-sparql](https://npm.io/package/graphql-to-sparql.md) ^5.0.0 - [sparqljson-to-tree](https://npm.io/package/sparqljson-to-tree.md) ^3.0.2 - [jsonld-context-parser](https://npm.io/package/jsonld-context-parser.md) ^2.1.0 ## Alternatives - [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads - [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads - [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads - [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads - [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads ## Recent versions - 2.0.0 (latest) — 2025-01-09 - 1.4.1 — 2022-11-09 - 1.4.0 — 2021-08-13 - 1.3.0 — 2021-07-30 - 1.2.0 — 2020-09-21 - 1.1.0 — 2020-04-03 - 1.0.1 — 2019-10-16 - 1.0.0 — 2019-06-13 - 0.0.1 — 2019-02-18 ## README # GraphQL-LD [![Build status](https://github.com/rubensworks/graphql-ld.js/workflows/CI/badge.svg)](https://github.com/rubensworks/graphql-ld.js/actions?query=workflow%3ACI) [![Coverage Status](https://coveralls.io/repos/github/rubensworks/graphql-ld.js/badge.svg?branch=master)](https://coveralls.io/github/rubensworks/graphql-ld.js?branch=master) [![npm version](https://badge.fury.io/js/graphql-ld.svg)](https://www.npmjs.com/package/graphql-ld) GraphQL-LD allows _Linked Data_ to be queried via _[GraphQL](https://graphql.org/)_ queries and a _[JSON-LD](https://json-ld.org/) 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. ?starring "Brad Pitt"@en. } } ``` 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" } } ``` ## Approach This library takes a GraphQL-LD query and a JSON-LD context as input, [converts it to a SPARQL query](https://github.com/rubensworks/graphql-to-sparql.js), sends the SPARQL query to a SPARQL query engine for execution ([local](https://github.com/rubensworks/graphql-ld-comunica.js) or [endpoint](https://github.com/rubensworks/graphql-ld-sparqlendpoint.js)), and [converts the SPARQL query results into a tree-based structure](https://github.com/rubensworks/sparqljson-to-tree.js) corresponding to the original GraphQL query. More information about this approach can be found in our [GraphQL-LD article](https://comunica.github.io/Article-ISWC2018-Demo-GraphQlLD/). ## Install ```bash $ yarn add graphql-ld ``` This package also works out-of-the-box in browsers via tools such as [webpack](https://webpack.js.org/) and [browserify](http://browserify.org/). ## Require ```javascript import {Client} from "graphql-ld"; ``` _or_ ```javascript var Client = require("graphql-ld").Client; ``` ## Usage ### With a client-side query engine _This requires you to install [graphql-ld-comunica](https://github.com/rubensworks/graphql-ld-comunica.js): `yarn add graphql-ld-comunica`._ _If you want to use this for Solid apps, have a look at [graphql-ld-comunica-solid](https://github.com/rubensworks/GraphQL-LD-Comunica-Solid.js) 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 }); ``` ### With a remote SPARQL endpoint _This requires you to install [graphql-ld-sparqlendpoint](https://github.com/rubensworks/graphql-ld-sparqlendpoint.js): `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 }); ``` ## 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](https://github.com/rubensworks/graphql-to-sparql.js). ### Finding all available labels 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", ... ] } } ``` ### Finding all movies Brad Pitt stars in 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" }, ... ] } ``` ### Finding all Belgian software developers 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" } }, ... ] } ``` ## License This software is written by [Ruben Taelman](http://rubensworks.net/). This code is released under the [MIT license](http://opensource.org/licenses/MIT). --- _Source: https://npm.io/package/graphql-ld · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._