@metreeca/wire-sparql

SPARQL 1.1 query language framework for @metreeca/wire storage connectors.

Provides a uniform Repository interface for issuing SPARQL queries and updates against any backend (an embedded store, a remote endpoint, or a managed server), without binding application code to a specific store or client. It also bundles the building blocks for working with the data exchanged, such as an RDF term model, DSLs for composing SPARQL queries and RDF graphs, and codecs for RDF serialisations.

Installation

Install this framework together with a backend connector for your target engine, plus any peer dependency the connector requires:

npm install @metreeca/wire-sparql                # the SPARQL query API (this framework)
npm install @metreeca/wire-sparql-<backend>      # backend connector from the table below
npm install <peer-dependency>                    # connector's peer dependency, where required
Copy

Usage

Querying a Backend

Obtain a Repository from any backend connector, then run SPARQL queries and updates through its methods:

import { createHTTPRepository } from "@metreeca/wire-sparql-http";

const repository = createHTTPRepository({
	query: "https://example.org/sparql",
	update: "https://example.org/sparql/statements"
});

await repository.update(`
	INSERT DATA { <https://example.org/widget> <https://schema.org/name> "Widget" }
`);

const tuples = await repository.select(`
	SELECT ?name { ?product <https://schema.org/name> ?name }
`); // readonly Tuple[]: each maps the ?name token to a Term

const present = await repository.ask(`ASK { ?s ?p ?o }`);

const triples = await repository.construct(`
	CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }
`); // readonly Triple[]

await repository.close();
Copy

Transactions

Bracket related operations with execute: the task runs on a per-call Repository and commits together, or rolls back if it throws:

await repository.execute(async tx => {
	await tx.update(`DELETE WHERE { <https://example.org/widget> ?p ?o }`);
	await tx.update(`INSERT DATA { <https://example.org/widget> <https://schema.org/name> "Gadget" }`);
});
Copy

Implementing a Connector

A backend connector implements the Repository interface (ask, select, construct, update, execute, and close), lifting native backend nodes into the shared term model with the reference, tagged, and typed constructors, and parsing or serialising RDF payloads with the codecs/ntriples module.

A minimal connector has the shape:

import type { Repository, SPARQL } from "@metreeca/wire-sparql";

function createMyRepository(/* endpoint, client, … */): Repository {

	const repository: Repository = {

		ask: async (query: SPARQL) => { /* run ASK; return the boolean */ },

		select: async (query: SPARQL) => { /* run SELECT; map bindings to Tuples of Terms */ },

		construct: async (query: SPARQL) => { /* run CONSTRUCT; map statements to Triples */ },

		update: async (update: SPARQL) => { /* apply the UPDATE */ },

		execute: async task => task(repository),  // or bracket the task in a backend transaction

		close: async () => { /* release resources, or no-op */ }

	};

	return repository;
}
Copy

Support

• open an issue to report a problem or to suggest a new feature
• start a discussion to ask a how-to question or to share an idea

License

This project is licensed under the Apache 2.0 License – see LICENSE file for details.