SPARQL HTTP Client

Common errors

• ReferenceError: require is not defined

  cause `sparql-http-client` version 3.x and above is an ES module and does not support CommonJS `require` syntax directly.
  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`).

• TypeError: Missing 'endpointUrl' option

  cause The `SparqlClient` (or other client variants) constructor was called without providing the necessary `endpointUrl` (or `updateUrl`/`storeUrl`) in the configuration object.
  fix Provide the SPARQL endpoint URL when initializing the client: `const client = new SparqlClient({ endpointUrl: 'https://query.wikidata.org/sparql' })`.

• No data received from SPARQL SELECT query stream

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Ensure the client is initialized with at least one URL, for example: `new SparqlClient({ endpointUrl: 'http://example.org/sparql' })`.
• gotcha 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.
  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.

Install

• npm install sparql-http-client npm
• yarn add sparql-http-client yarn
• pnpm add sparql-http-client pnpm

Imports

• SparqlClient
  wrong:

  const SparqlClient = require('sparql-http-client')

  correct:

  import SparqlClient from 'sparql-http-client'

  The primary client, which defaults to streaming behavior. CommonJS `require` is not supported since v3.
• SimpleClient
  wrong:

  import SimpleClient from 'sparql-http-client'

  correct:

  import { SimpleClient } from 'sparql-http-client'

  For a simpler, fetch-like client that returns raw HTTP responses. This is a named export, not a default.
• ParsingClient

  import { ParsingClient } from 'sparql-http-client'

  Provides automatic parsing of SPARQL results into RDF/JS DatasetCore objects or arrays. This is a named export.

Quickstart

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.

import SparqlClient from 'sparql-http-client'

const endpointUrl = 'https://query.wikidata.org/sparql'
const query = `
PREFIX wd: <http://www.wikidata.org/entity/>
PREFIX p: <http://www.wikidata.org/prop/>
PREFIX ps: <http://www.wikidata.org/prop/statement/>
PREFIX pq: <http://www.wikidata.org/prop/qualifier/>

SELECT ?value WHERE {
  wd:Q243 p:P2048 ?height.

  ?height pq:P518 wd:Q24192182;
    ps:P2048 ?value .
}`

async function runQuery() {
  const client = new SparqlClient({ endpointUrl })
  const stream = await client.query.select(query)

  return new Promise((resolve, reject) => {
    stream.on('data', row => {
      for (const [key, value] of Object.entries(row)) {
        console.log(`${key}: ${value.value} (${value.termType})`)
      }
    })

    stream.on('end', () => {
      console.log('Query finished.')
      resolve()
    })

    stream.on('error', err => {
      console.error('Stream error:', err)
      reject(err)
    })
  })
}

runQuery().catch(console.error)