{"id":15835,"library":"sparql-http-client","title":"SPARQL HTTP Client","description":"sparql-http-client is a JavaScript client library designed to simplify interactions with SPARQL endpoints, covering SPARQL Queries, Updates, and Graph Store operations. It abstracts the complexities of the SPARQL Protocol and SPARQL Graph Store Protocol, offering a streamlined API. The current stable version is 3.1.0, and the project appears to be actively maintained, indicated by recent version updates and a healthy GitHub repository. A key differentiator is its provision of multiple client 'flavors': the default `SparqlClient` (also known as `StreamClient`) which leverages Node.js streams for processing results from `SELECT`, `CONSTRUCT`, and `DESCRIBE` queries; a `SimpleClient` that aligns more closely with the `fetch` API for direct response handling; and a `ParsingClient` that automatically wraps results into RDF/JS DatasetCore objects or arrays. This flexibility allows developers to choose the most suitable interface for their specific use case, whether it's processing large result sets via streams or quickly retrieving parsed RDF data.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/rdf-ext/sparql-http-client","tags":["javascript","sparql","http","rdf"],"install":[{"cmd":"npm install sparql-http-client","lang":"bash","label":"npm"},{"cmd":"yarn add sparql-http-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add sparql-http-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for RDF/JS environment setup and data factories.","package":"@rdfjs/environment","optional":false},{"reason":"Provides core RDF/JS TypeScript interfaces for data models and datasets.","package":"@rdfjs/types","optional":false},{"reason":"Used by the default StreamClient for handling SPARQL query results as Node.js streams.","package":"readable-stream","optional":false},{"reason":"Provides a fetch API implementation for Node.js environments, especially for versions prior to native fetch support.","package":"node-fetch","optional":false}],"imports":[{"note":"The primary client, which defaults to streaming behavior. CommonJS `require` is not supported since v3.","wrong":"const SparqlClient = require('sparql-http-client')","symbol":"SparqlClient","correct":"import SparqlClient from 'sparql-http-client'"},{"note":"For a simpler, fetch-like client that returns raw HTTP responses. This is a named export, not a default.","wrong":"import SimpleClient from 'sparql-http-client'","symbol":"SimpleClient","correct":"import { SimpleClient } from 'sparql-http-client'"},{"note":"Provides automatic parsing of SPARQL results into RDF/JS DatasetCore objects or arrays. This is a named export.","symbol":"ParsingClient","correct":"import { ParsingClient } from 'sparql-http-client'"}],"quickstart":{"code":"import SparqlClient from 'sparql-http-client'\n\nconst endpointUrl = 'https://query.wikidata.org/sparql'\nconst query = `\nPREFIX wd: <http://www.wikidata.org/entity/>\nPREFIX p: <http://www.wikidata.org/prop/>\nPREFIX ps: <http://www.wikidata.org/prop/statement/>\nPREFIX pq: <http://www.wikidata.org/prop/qualifier/>\n\nSELECT ?value WHERE {\n  wd:Q243 p:P2048 ?height.\n\n  ?height pq:P518 wd:Q24192182;\n    ps:P2048 ?value .\n}`\n\nasync function runQuery() {\n  const client = new SparqlClient({ endpointUrl })\n  const stream = await client.query.select(query)\n\n  return new Promise((resolve, reject) => {\n    stream.on('data', row => {\n      for (const [key, value] of Object.entries(row)) {\n        console.log(`${key}: ${value.value} (${value.termType})`)\n      }\n    })\n\n    stream.on('end', () => {\n      console.log('Query finished.')\n      resolve()\n    })\n\n    stream.on('error', err => {\n      console.error('Stream error:', err)\n      reject(err)\n    })\n  })\n}\n\nrunQuery().catch(console.error)\n","lang":"typescript","description":"This example demonstrates how to initialize the default `SparqlClient`, execute a `SELECT` query against a public SPARQL endpoint (Wikidata), and process the streaming results asynchronously. It logs each binding from the result rows."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or use dynamic `import()` for CommonJS contexts, if absolutely necessary, though direct `require` is not supported.","message":"Version 3.x of `sparql-http-client` transitioned to being an ESM-only package. Direct `require()` statements for importing the library will no longer work, leading to runtime errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure the client is initialized with at least one URL, for example: `new SparqlClient({ endpointUrl: 'http://example.org/sparql' })`.","message":"All client constructors (`SparqlClient`, `SimpleClient`, `ParsingClient`) require at least one URL argument (`endpointUrl`, `updateUrl`, or `storeUrl`) in their options object. Omitting all of them will result in an error or disable specific capabilities.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always check the return type for the specific query operation. For streams, ensure proper stream consumption. For Promises, use `await` or `.then()` to handle the result.","message":"Different query types return different result formats and mechanisms. `client.query.select()` and `client.query.construct()` return Node.js readable streams, which must be consumed (e.g., using `stream.on('data')` or `for await...of`). `client.query.ask()` and `client.query.update()` return Promises that resolve to a boolean or void, respectively.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change your import statements from `const SparqlClient = require('sparql-http-client')` to `import SparqlClient from 'sparql-http-client'` and ensure your project is configured for ES modules (e.g., `\"type\": \"module\"` in `package.json`).","cause":"`sparql-http-client` version 3.x and above is an ES module and does not support CommonJS `require` syntax directly.","error":"ReferenceError: require is not defined"},{"fix":"Provide the SPARQL endpoint URL when initializing the client: `const client = new SparqlClient({ endpointUrl: 'https://query.wikidata.org/sparql' })`.","cause":"The `SparqlClient` (or other client variants) constructor was called without providing the necessary `endpointUrl` (or `updateUrl`/`storeUrl`) in the configuration object.","error":"TypeError: Missing 'endpointUrl' option"},{"fix":"Ensure you are consuming the stream by attaching 'data' event listeners and an 'end' listener, or by using `for await (const row of stream)` if your environment supports async iterators.","cause":"When using `client.query.select()` or `client.query.construct()`, the method returns a Node.js readable stream. If the stream is not actively consumed (e.g., listening for 'data' events or using async iterators), no data will be processed.","error":"No data received from SPARQL SELECT query stream"}],"ecosystem":"npm"}